...
Generated AsciiDoc is included in Groovy Server Page templates (these live in https://github.com/apache/incubator-netbeans-website/tree/master/netbeans.apache.org/src/content/templates ). These are responsible for the layout of the web pages. The AsciiDoc content is a Java String with all the generated HTML (but the <head> stuff) and is referenced using "$content.body" inside the Groovy Server Page.
...
See the AsciiDoctor Writer's Guide for more information https://asciidoctor.org/docs/asciidoc-writers-guide/
Tip: In general we should make the tutorials be less wordy, less long paragraphs.
Special Constructs and Best Practices
...
Screenshots should be at least 640px wide?? (what's a good size for retina images?). PNG is preferred (isn't it?)
Info |
---|
Images inline in a table might not show if defined as: |image::images/changes-head-index.png[] |*Changes between HEAD and Index* |Displays a list of files that are staged. For the image to show correctly this line will need to be changed to: |image:images/changes-head-index.png[] |*Changes between HEAD and Index* |Displays a list of files that are staged. Note the single colon and the new line. |
Clickable screenshots
Clickable screenshots are generated using a "[.feature]" tag above a paragraph that contains the image. This allows us to have a small image (the focuses on a part of the screenshot) that the user can click to see a larger image. The AsciiDoc construct for these is like so:
[.feature]
-- image::images/the-title-of-the-image-small.png[role="left", title="Click to enlarge", link="images/the-title-of-the-image-big.png"] --
Tip: Be sure to add a newline before the [.feature]
tag
Youtube videos
Use the "video" asciidoc macro to embed youtube videos, like so:
...
Other languages are "html", "xml", "javascript", "php", "python", "ruby". Remember to use the ":syntax: true" atribute in the metadata so that syntax highlighting works.
Restarting numbered lists
Numbered lists that have in-between paragraphs often restart numbering. So, for instance, you have item 1, item 2, then a paragraph and then the next item starts again at 1. Remember that you can tell asciidoc to start a numbered list on a certain number using the "start" tag, like so:
1. This is the first item
2. This is the second item
Now we have a paragraph here, or an image or whatever
[start=3]
3. This is the third item
Admonitions
Use NOTE: and TIP: for admonitions. These must be in capital letters, without any asterkisks around them:
NOTE: This is a note
If you use these admonitions be sure to add the
:icons: font
on the metadata of the page, so that admonitions have proper icons.
Icons
To use font awesome icons in your webpage include the :icons: font
in the metadata of the page.
Then you can reference an icon using the name of the icon in the asciidoc icon macro, like so:
.icon:users[]
for a list of icons see https://fontawesome.com/icons?d=gallery
For instance, to include the https://fontawesome.com/icons/adjust?style=solid adjust icon, use the construct
.icon:adjust[]
Other enhancements
Please discuss any issue you may have with asciidoc and the website in general in the dev mailing list.
...