Styleguide
General guidelines
-
Remove spaces in folder names and filenames.
Incorrect Correct My File.adocMyFile.adocQuick Start/QuickStart/imagetitle.pngImageTitle.png -
Remove hyphens in folder names and filenames.
Incorrect Correct Release-Notes.adocReleaseNotes.adocTech-Notes/TechNotes/image-title.pngImageTitle.png -
Use PascalCase for all filenames and folder names.
Incorrect Correct styleguide.adocStyleguide.adocreleaseNotes/ReleaseNotes/ -
Avoid having more than one blank line anywhere in an AsciiDoc document.
Incorrect Correct == Section A == Section B
== Section A == Section B
-
Avoid trailing spaces at the end of any line.
How to enable auto-trimming in Visual Studio CodeTo handle this automatically in Visual Studio Code, open Settings (Ctrl+,), search for
Trim Trailing Whitespace, and enable the checkbox. This will remove trailing spaces every time you save a file. -
Keep lines under 100 characters. Split longer lines into multiple lines.
How to add a vertical ruler in Visual Studio CodeTo visually identify long lines, add a ruler at column 100 in Visual Studio Code. Open Settings (Ctrl+,), search for
Editor: Rulers, click Edit in settings.json, and add the following:"editor.rulers": [100]This displays a vertical line at column 100, making it easy to spot lines that need to be split.
Incorrect Correct This is a very long line that exceeds the hundred character limit and makes the document harder to read and review.
This is a very long line that exceeds the hundred character limit and makes the document harder to read and review.
Links
Cross-references (links within the documentation)
Use xref: to link to other pages within the documentation. The path is relative to the current file. The format is xref: followed by the relative path, a # separator, and the link text in square brackets.
| AsciiDoc markup | Result |
|---|---|
|
|
|
To link to a specific section within a page, append the section anchor after #:
xref:Index#_documentation_index[Documentation Index] renders as Documentation Index
External links
Use link: or a bare URL to link to external websites.
link:https://example.com[Link Text]link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]To link to a specific section on an external page, include the anchor in the URL:
link:https://fluxbook-en.onrender.com/bend/editing/editbend.html#_editing_a_hem_bend[Editing a Hem Bend]Images
Every AsciiDoc file that uses images should declare the images directory at the top of the file using :imagesdir: img. This tells AsciiDoc to look for images in the img folder relative to the current file. Save all images as .png files using PascalCase naming in the corresponding img folder.
Block images
Block images appear on their own line and are used for screenshots, diagrams, and figures. The syntax uses image followed by two colons, the filename, and attributes in square brackets.
| Format | Description |
|---|---|
|
Basic block image with alt text |
|
Block image with a named width attribute |
|
Block image with width as a positional attribute |
Inline images
Inline images appear within a line of text, such as icons or small graphics. Use image followed by a single colon instead of two.
For example, Click the image:Icon.png[Button,16] renders a small image inline with the text.
Image titles
Add a title above a block image using a . prefix on the line before the image declaration. For example:
.Git workflow overview
image::Workflow.png[]
This renders a captioned figure with the title displayed above the image.
Keyboard shortcuts
Use the kbd:[] macro to display keyboard shortcuts in a styled format. This requires the :experimental: attribute to be set at the top of the file.
The format is kbd: followed by the key combination in square brackets. Use + to separate multiple keys in a combination.
| AsciiDoc markup | Result |
|---|---|
|
Ctrl+C |
|
Ctrl+Shift+P |
|
Enter |
|
Ctrl+, |
|
F5 |
Use keyboard shortcuts inline with text:
Press kbd:[Ctrl+S] to save the file.
This renders as: Press Ctrl+S to save the file.