...
The NetBeans website is written mainly in AsciiDoc (but MarkDown and HTML is possible). We prefer plain AsciiDoc when possible, so AsciiDoc generates the HTML for us, and we just customize how the HTML looks using CSS. Also content can be later transformed to EPUB / PDF more easily.
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.
...