Page History

...

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?)

|image::images/changes-head-index.png[] |*Changes between HEAD and Index* |Displays a list of files that are staged.

|image:images/changes-head-index.png[]

|*Changes between HEAD and Index* |Displays a list of files that are staged.

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.

...