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/
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?)
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"] --
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.
Other enhancements
Please discuss any issue you may have with asciidoc and the website in general in the dev mailing list.