Tutorial Contribution Guidelines
Last reviewed on 2019-01-25
- The NetBeans Web Site
- AsciiDoc Conventions in Apache NetBeans
- The Content
The Apache NetBeans Tutorials were included in the third donation from Oracle to the Apache Software Foundation. Many of these tutorials need to be reviewed. Everybody can help out in the review process. All you need is a web browser, a GitHub account and a basic knowledge of AsciiDoc.
This page describes some tips, tricks and conventions for reviewing tutorials for Apache NetBeans.
The NetBeans Web Site
The NetBeans website is written mainly in AsciiDoc, a way of creating technical components using plain text files.
We then generate HTML for the web using Groovy Server Page templates (these live in https://github.com/apache/incubator-netbeans-website/tree/master/netbeans.apache.org/src/content/templates ). These templates (and some other stuff like SCSS) are responsible for the layout of the web pages.
|The generated HTML is responsive, this is, it can be correctly visualized in mobile phones.|
Direct editing in GitHub
All web pages can be edited directly in GitHub. To do so follow these instructions:
Click the "See this page in GitHub" link at the bottom of any page.
You will then be redirected to GitHub. Once there click the "Edit this file" button.
If you don’t have edit permissions you always can clone the website repository in GitHub and then edit the file in your own clone, and then submit that as a Pull Request against the main Apache Repository.
AsciiDoc Conventions in Apache NetBeans
.asciidoc pages must have a license header stating the Apache License and the Apache Software Foundation ownership. The Apache license header is included as an asciidoc comment, like so:
// // Licensed to the Apache Software Foundation (ASF) under one // or more contributor license agreements. See the NOTICE file // distributed with this work for additional information // regarding copyright ownership. The ASF licenses this file // to you under the Apache License, Version 2.0 (the // "License"); you may not use this file except in compliance // with the License. You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, // software distributed under the License is distributed on an // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY // KIND, either express or implied. See the License for the // specific language governing permissions and limitations // under the License. //
All tutorials must start with a "Level 0" title with a single equal sign. This will be the title of the page. You write a title like so:
= This is a title
It is an error if there’s any content before the level 0 title (but for comments). If you see any content above the title then please move it below the title (that’s called the "AsciiDoc Preamble").
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 :reviewed: 2019-01-25 :syntax: true :source-highlighter: pygments :toc: left :toc-title: :icons: font :description: NetBeans IDE Java Quick Start Tutorial - Apache NetBeans :keywords: Apache NetBeans, Tutorials, NetBeans IDE Java Quick Start Tutorial
This is a small description of the metadata:
reviewed: set this to the date the tutorial was reviewed, for instance, 2019-01-25.
tutorialfor tutorial pages,
wikifor wiki pages,
pagefor simple pages.
tutorialsfor tutorials, feel free to any tags of your liking (we should formalize this).
jbake-status: always set it to
trueif this page contains source code that has to be syntax-highlighted. Please also add
tocSet always to left.
fontfor adding support for FontAwesome icons.
description: set to something that describes the page. This is used for SEO.
keywords: keywords describing the page. This is used for SEO.
Write the rest of the page using plain AsciiDoc. See the AsciiDoctor Writer’s Guide for more information https://asciidoctor.org/docs/asciidoc-writers-guide/
You can structure the content using sections. Start each section with a level 1 header, that must have at least two equal signs (but can have more for subsections), like so:
== This is a section header Some content here === This is a subsection Some more stuff here
|In general we should make the tutorials be less wordy, less long paragraphs. Special Constructs and Best Practices.|
Inline screenshots and images
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 in a table should be inlined, i.e., using the
single colon image construct, like so:
Block images and screenshots
Block images are inserted using the
image:: AsciiDoc construct, this is, with two colons. These take a
paragraph of their own. Example:
image::images/image.png[title="This is the image caption"]
|Note the two colons for block images, and a single colon for inlined (in the paragraph) images.|
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"] --
Be sure to add a newline before the
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
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
ruby. Remember to use the
:syntax: true atribute in the metadata so that syntax highlighting works.
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 (notes, tips)
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
on the metadata of the page, so that admonitions have proper 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:
for a list of icons see https://fontawesome.com/icons?d=gallery
If you need to include a new feature in the page then please request for it in our Dev Mailing List.