asciidoctor / asciidoctor.org Goto Github PK
View Code? Open in Web Editor NEW:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
Home Page: https://asciidoctor.org
License: Other
:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
Home Page: https://asciidoctor.org
License: Other
In the new users guide it says:
Section levels cannot be chosen arbitrarily. There are two rules you must follow:
Does this mean that other doctypes can have multiple level 0 sections or can they have none?
This will need to be done so the examples in the release notes display correctly.
Add parts and sections from template into user manual to determine what documentation is missing.
Render Alex's java integration ReadMe on the website and interconnect it with the other guides.
Update the index page
Transfer Asciidoctor Maven readme content to appropriate webpage
Pull base content from the 0.1.4 release notes and this discussion:
In the AsciiDoc syntax quick ref, document how to give attributes in the document precedence over attributes defined by the caller (API or CLI).
Normally, an attribute defined by the caller overrides the attribute with the same name defined in the document. However, if you add a trailing @
to the attribute value, the declaration in the document takes precedence.
The showcase page should highlight places where Asciidoctor is used, projects that build on it and projects that integration with it.
Examples include:
We should also add a testimonials page. If that should be a different page than this one, split that off into another issue (best not to bundle issues).
How do the two syntaxes differ?
Partners with the Asciidoctor and AsciiDoc differences
May go under The Basics category
It's time to iterate over all the published Docs Headers and create a default header that can be pasted in as a good starting point when a new guide is created.
This will minimize the need to come up with link names that are used repeatedly and make sure each guide has the right attributes for the website stylesheet.
Below are just a few examples of how different the attribute lists are from Doc to Doc:
Example 1 (Header from Quick Ref):
:awestruct-layout: base
:awestruct-javascripts: [view-result]
:description: This guide is a quick reference for the common formatting markup and document elements in the AsciiDoc syntax.
:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet
:imagesdir: ../images
:toc:
:toc-placement!:
ifndef::awestruct[]
:idprefix:
:idseparator: -
endif::awestruct[]
:result: role="result"
:linkattrs:
Example 2 (Header from MacOSX Guide)
:awestruct-layout: base
:toc:
:toolchain: link:
Example 3: (Header from How do I render....)
:awestruct-layout: base
:toc:
Examples of the variety of link naming schemes:
Example 1: (Header links from How do I render...)
:toolchain: link:/docs/install-toolchain
:buildref: http://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/README.adoc
:factoryrepo: http://github.com/asciidoctor/asciidoctor-stylesheet-factory
:factoryshowcase: http://themes.asciidoctor.org/
:customthemeref: http://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/README.adoc#create-a-new-theme
:yelp: http://live.gnome.org/Yelp
:publican: http://fedorahosted.org/publican
:a2x: http://asciidoc.org/a2x.1.html
:backendrepo: http://github.com/asciidoctor/asciidoctor-backends
:backendissue: http://github.com/asciidoctor/asciidoctor-backends/issues
:mailinglist: http://discuss.asciidoctor.org/
:userguide: http://asciidoc.org/userguide.html
Example 2: (Header links from Writers Guide)
:asciidoc-ref: http://asciidoc.org
:asciidoc-dl-ref: http://sourceforge.net/projects/asciidoc/files/latest/download
:asciidoc-editor-ref: http://asciidoc.org/#_editor_support
:asciidoc-faq-ref: http://asciidoc.org/faq.html
:asciidoc-guide-ref: http://asciidoc.org/userguide.html
:asciidoc-install-ref: http://asciidoc.org/INSTALL.html
:asciidoc-list-ref: http://groups.google.com/group/asciidoc
:asciidoctor-ref: link:/
:asciidoctor-gem-ref: https://rubygems.org/gems/asciidoctor
:deckjs-ref: http://imakewebthings.com/deck.js
:editing-ref: link:/docs/editing-asciidoc-with-live-preview/
:gist-ref: http://gist.github.com
:publican-ref: https://fedorahosted.org/publican
:quick-ref: link:/docs/asciidoc-quick-reference/
:what-asciidoc-ref: link:/docs/what-is-asciidoc-why-use-it
Your syntax guide is a subset of the canonical cheatsheet - http://powerman.name/doc/asciidoc.
For example, look at headers - you only seem to accept the
=== Header
style rather than
Header
It seems like your implementation is not correct if you don't match the original. Please make sure you match the original and canonical guide.
For an example please see
https://github.com/thesteve0/osbeginnerguide/blob/master/Intro.asciidoc
Not all video formats can be used with the video tag. Make a note of this in the documentation / writer's guide. Something along the lines of:
The HTML 5 video tag does not support the Quicktime/Sorenson format for video. It first needs to be converted to a "web-friendly" video format. That explains why nothing happens when you press the play button.
The following article is an excellent resource for explaining how to prepare video for an HTML 5 page.
http://www.htmlgoodies.com/html5/client/how-to-embed-video-using-html5.html#fbid=ensvc_rW_lt
You can ignore the parts about the HTML elements since Asciidoctor is already generates that. What's important are the video formats.
* While there are ways to embed Quicktime/Sorenson using object/embed tags, these are considered deprecated and using a web-friendly video format is strongly recommended.
I have this input:
RHQ
===
Heiko W. Rupp <[email protected]>
:Author Initials: HWR
:toc:
:icons:
:numbered:
:website: http://www.pilhuhn.de/hwr
:author: Heiko W. Rupp`
asciidoc creates
<bookinfo>
<title>RHQ</title>
<author>
<firstname>Heiko</firstname>
<othername>W.</othername>
<surname>Rupp</surname>
<email>[email protected]</email>
</author>
<authorinitials>HWR</authorinitials>
</bookinfo>
(see the correct split into firstname and surname etc.
asciidoctor creates
<bookinfo>
<title>RHQ</title>
<date>2013-01-31</date>
<author>
<firstname>Heiko W. Rupp <[email protected]></firstname>
</author>
<authorinitials>HWR</authorinitials>
Write a tutorial that covers how to write a blog entry in AsciiDoc for an Awestruct site*.
Here's a rough outline that identifies the scope of the tutorial:
* We may be able to update this tutorial in the future to include steps for using other static-site generation tools once they offer similar AsciiDoc integration to Awestruct.
Include updates per Asciidoctor 0.1.2
As the goal of the new users guide is to be brief and to get them writing in AsciiDoc ASAP, I think most of the content prior to the Writing in AsciiDoc: First Steps section is just way too much backstory.
What do people think of removing most of that content and instead use it to create "What is AsciiDoc", "Why Use AsciiDoc", "How AsciiDoc Renders your Opus" guides?
Change X's to use attribute check mark styles in header
Include code snippets showing new attributes and Font Awesome icons.
Link to appropriate guides with updated/expanded examples.
Docs have been published by index page lacks links.
Refer to comments in this pull request: #55
This information is now available in the Docs section under How do Asciidoctor and AsciiDoc differ?
Ref: Pull Request #92
The styles on asciidoctor.org are similar to the ones from the default Asciidoctor stylesheet, but does not share a common build. That means every change to the default Asciidoctor stylesheet also has to be made to the website.
Incorporate the default Asciidoctor stylesheet into the website so that the website can inherit the styles needed for styling HTML generated by Asciidoctor.
Add a link to the following script on the migrations page that converts Confluence XHTML to AsciiDoc:
Add the following clarification to the writer's guide and quick reference (if it fits).
Constrained means "around a word". Unconstrained means "anywhere".
This is almost done, I just need to polish it and pick a picture.
There are some amazing aspects released on Asciidoctor 0.1.3 that are documented in news section but not in AsciiDoc Syntax Quick Reference. I think would be good have all features documented in a single document so anyone new can learn all features without having to read more than one document.
Move the Markdown syntax to its own section at the bottom of the Quick Ref guide.
I can't see a difference between the text written in AsciiDoc syntax to showcase wrapping and the rendered output. If I'm reading the example correctly, I think the output is supposed to be wrapped...but it's not. So either the example text is wrong or the explanation of the example is wrong.
From document:
In other words, you write AsciiDoc like you’re writing an e-mail.
Wrapping lines of text:
Adjacent lines like these are combined to form a single paragraph.
That means you can wrap paragraph text
or put each sentence on a separate line
and the line breaks won't appear in the output.
Here’s how the previous lines look when rendered:
Adjacent lines like these are combined to form a single paragraph.
That means you can wrap paragraph text
or put each sentence on a separate line
and the line breaks won't appear in the output.
People are often asking which editor they should use for AsciiDoc (phrased as "what's a good AsciiDoc editor?"). Of course, our stance is that you don't need a special editor. We can make that point, but also recommend editors that have good syntax highlighting and perhaps embedded preview.
We want to make sure to recommend open source options first, but I guess it would be biased if we didn't list non-open source editors that are know to be very good (such as Sublime).
The base content is here: http://discuss.asciidoctor.org/Hyperlinks-with-multiple-underscores-td558.html
Be a little crazy
After using the quick reference guide for myself, I realize it is long and scrolling up and down it looking for a specific tip gets tiring.
Include new properties and configuration options
Add and update content per new release and new funtions
As this question comes up frequently, document explicitly the various ways to enable custom substitutions on a block, in particular a listing/source block.
Custom substitutions are supported on the source block (and any block, for that matter):
[source,java]
[subs="verbatim,quotes"]
----
System.out.println("Hello *bold* text").
----
If you want to enable the quotes in an ad-hoc way, then you'll want to enable macros on the block and use the inline pass:[]
macro, which allows substitutions to be specified:
[source,java]
[subs="verbatim,macros"]
----
System.out.println("No *bold* here");
pass:verbatim,quotes[System.out.println("Hello *bold* text");]
----
The inline pass:[]
macro does introduces additional markup into the Java source that makes it invalid in raw form, but the output it produces will be valid when viewed in a viewer (HTML, PDF, etc).
Related discussion post:
http://discuss.asciidoctor.org/Bold-Source-Code-and-Escaping-td464.html
Update the Editing with Live Preview docs to feature all recommended approaches to editing AsciiDoc.
This page should include:
And perhaps others as needed.
In response to a question raised on the mailinglist, document how to link to a common stylesheet location when processing documents in subdirectories.
For more details and proposed solutions, see the following mailinglist thread:
http://discuss.asciidoctor.org/Single-CSS-for-multiple-nested-adoc-files-td552.html
Add content from the project's readme to the documentation website.
In the installation guide, should the Asciidoctor instructions come first?
Per @mojavelinux comment when doc was first published to website.
Currently, the AsciiDoc syntax quick reference is trying to serve both newcomers and veteran users. The more complete it becomes, the more intimidating it makes the AsciiDoc syntax seem for newcomers.
Spin off a more basic AsciiDoc syntax quick reference that has the scope of a Markdown reference (specifically a Markdown variant, like Kramdown, that supports the most common extras).
Have difference as their own .adoc
Add new link to Docs index page
Add:
Pull the content from the stylesheet factory website into the documentation
Render ReadMe to the Docs section
Update the Index page
Remove links to ReadME from documentation index
Will include instructions for both Asciidoctor, AsciiDoc, and a2x
right
now works with multiple attributes
To make the purpose / function of this repository more clear, rename it to asciidoctor.org.
The following steps need to be performed to complete this change:
Create a table that catalogs all the attributes recognized by Asciidoctor and the acceptable values. Include a description of each attribute, where it can be specified (cli, document, etc) and under what circumstances.
Guide includes the optional/alternate/advanced metadata and style attributes/values to customize the look and feel of your document.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.