Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
evergreen-docs:dig_style_guide [2020/10/27 10:48] – [Changes to cross-reference structure] aneiman | evergreen-docs:dig_style_guide [2021/05/28 14:36] – aneiman |
---|
==== Add a Table of Contents to the top of each AsciiDoc file ==== | ==== Add a Table of Contents to the top of each AsciiDoc file ==== |
| |
This simply means adding this AsciiDoc line near the top of each ''.adoc'' file. (The old system added this during the HTML build process.) | This simply means adding this AsciiDoc line near the top of each ''.adoc'' file. The toc designation should go on the 2nd line of your file, just below the top header. (The old system added this during the HTML build process.) |
| |
<code asciidoc>:toc:</code> | |
| |
==== Use underline style headings instead of prefix/suffix style ==== | <code asciidoc>= Heading = |
| :toc:</code> |
| |
| |
| |
| ==== Use prefix/suffix style headings instead of underline style ==== |
| |
The basic reasons are: | The basic reasons are: |
* ''reports'' - indicates the folder in the docs/modules/ directory | * ''reports'' - indicates the folder in the docs/modules/ directory |
* ''reporter_folder.adoc'' - indicates the specific file being referenced | * ''reporter_folder.adoc'' - indicates the specific file being referenced |
* ''reporter_creating_folders'' - indicates the subheading being linked to within the file | * ''reporter_creating_folders'' - indicates the subheading or anchor being linked to within the file |
* ''[Creating Folders]'' - the link text that is displayed | * ''[Creating Folders]'' - the link text that is displayed |
| |
For historical purposes, the old xref syntax is below | For historical purposes, the old xref syntax is below |
| |
**DO NOT USE THIS!** The below is an example of the now-deprecated cross reference style: | The below is an example of the now-deprecated cross reference style. **DO NOT USE THIS!** |
<code asciidoc> | <code asciidoc> |
<<reporter_creating_folders,Creating Folders>> | <<reporter_creating_folders,Creating Folders>> |
* **Don't add a border or shadow** to the screenshot image. That can be done globally to all screenshots in the docs via CSS, if we want it. | * **Don't add a border or shadow** to the screenshot image. That can be done globally to all screenshots in the docs via CSS, if we want it. |
* **When replacing a screenshot**, if the intention of the image isn't changing, then create a new image with the same file name as the old image. However, if you are essentially removing a screenshot and adding a different one (with a different focus or purpose), it is better to use a different file name (and update the reference to it in the docs!), and probably to change the related text in the documentation also. | * **When replacing a screenshot**, if the intention of the image isn't changing, then create a new image with the same file name as the old image. However, if you are essentially removing a screenshot and adding a different one (with a different focus or purpose), it is better to use a different file name (and update the reference to it in the docs!), and probably to change the related text in the documentation also. |
| * Image syntax: ''image::media/filename.png[alt text]''. If the image file is within the same module parent directory as the file containing the image link, you don't need to further enumerate the path. Please remember to include alt text for descriptive and accessibility reasons. |
| * Screen shots can be from any installation of Evergreen, as long as it does not contain any personal identifiable information, and is based on stock Evergreen. |
===== Common Mistakes ===== | ===== Common Mistakes ===== |
| |
* AsciiDoc lists (numbered or bulleted) need to be preceded by a blank line. If not, they will be absorbed into the previous paragraph of text, like this: | * AsciiDoc lists (numbered or bulleted) need to be preceded by a blank line. If not, they will be absorbed into the previous paragraph of text, like this: |
* ''Here's a list: . Item 1 . Item 2 . Item 3'' | * ''Here's a list: . Item 1 . Item 2 . Item 3'' |
* Callouts should be formatted as ''<1>'' and not as ''<--! <1> -->'' | * Callouts should be formatted as ''<1>'' and not as ''<––! <1> ––>'' |
* Images, text blocks, or code blocks that are part of a numbered lists need to have a ''+'' preceding and following the image or block so the numbering continues in the correct order. See example below. | * Images, text blocks, or code blocks that are part of a numbered lists need to have a ''+'' preceding and following the image or block so the numbering continues in the correct order. See example below. |
| |