Versions Compared

Old Version 1

changes.mady.by.user Antonio Vieiro

Saved on

compared with

New Version Current

changes.mady.by.user Antonio Vieiro

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

...