This page describes some tips & tricks for writing web pages for the Apache NetBeans website using AsciiDoc.

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.

License

All .asciidoc pages must have a license header stating the Apache License and the Apache Software Foundation ownership. Just copy and paste from other page.

Level 0 title

All pages must start with a "Level 0" title with a single equal sign. This will be the title of the page:

= This is a level 0 heading

It is an error if there's any content before the level 0 title. Move it below the title (that's called the "AsciiDoc Preamble").

Metadata

Immediately after the level 0 title, we add the metadata of the page, all the "jbake-" entries are mandatory. Some others are commented below:

:jbake-type: tutorial
:jbake-tags: tutorials
:jbake-status: published
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: NetBeans IDE Java Quick Start Tutorial - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, NetBeans IDE Java Quick Start Tutorial
  • jbake-type: use 'tutorial' for tutorial pages, 'wiki' for wiki pages, 'page' for simple pages.
  • jbake-tags: use 'tutorials' for tutorials, feel free to any tags of your liking (we should formalize this).
  • jbake-status: always set it to 'published'
  • Set 'syntax' to true if this page may contain code that should be syntax-highlighted. Do not add the 'syntax' key otherwise.
  • toc Set always to left.
  • toc-title Leave empty.
  • description: set to something that describes the page. This is used for SEO.
  • keywords: keywords describing the page. This is used for SEO.

Content

Write the rest of the page using plain AsciiDoc. Do not use "Level 0" headers in the content (i.e., headers should be at least level 1, this is, two equal signs or greater).

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

We use some special AsciiDoc constructs to add additional features to the webpages. This section describes some of these.

Screenshots

Images related to a webpage are usually included in a "images/" subdirectory close to the webpage.

Screenshots should be at least 640px wide?? (what's a good size for retina images?). PNG is preferred (isn't it?)

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:

video::the-youtube-video-identifier[youtube, title="The title"]

where "the-youtube-video-identifier" is the id of the youtube video, for instance O8cwpEY1OAQ is the identifier for https://www.youtube.com/embed/O8cwpEY1OAQ

Source code

Use the plain asciidoc construct for source code excerpts (that is, four slashes). Please the the "lang" attribute accordingly, for instance, for Java:

[source,java]
----
System.out.println("Hello, world");
----

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.


  • No labels