evergreen-docs:dig_style_guide
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
| evergreen-docs:dig_style_guide [2019/07/11 15:28] – dluchenbill | evergreen-docs:dig_style_guide [2020/06/05 12:57] – lfloyd | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== DIG AsciiDoc Style Guide (draft) ====== | ====== DIG AsciiDoc Style Guide (draft) ====== | ||
| + | |||
| + | ===== Proposal: Antora with Some AsciiDoc Changes ===== | ||
| + | |||
| + | A small working group has been testing Antora as a new " | ||
| + | |||
| + | In addition to these minor changes, the **working group proposes the following changes**, which are not necessary for using Antora but we believe would make the docs better. | ||
| + | |||
| + | ==== Add a Table of Contents to the top of each AsciiDoc file ==== | ||
| + | |||
| + | This simply means adding this AsciiDoc line near the top of each '' | ||
| + | |||
| + | <code asciidoc>: | ||
| + | |||
| + | ==== Convert all headings from underline style to prefix/ | ||
| + | |||
| + | The basic reasons are: | ||
| + | |||
| + | * It's hard to remember which character means which level heading | ||
| + | * It's hard to maintain the correct number of characters (must match length of heading line) | ||
| + | * Prefix/ | ||
| + | |||
| + | **Example: Change this** | ||
| + | <code asciidoc> | ||
| + | Heading 1 | ||
| + | --------- | ||
| + | </ | ||
| + | |||
| + | **To this** | ||
| + | <code asciidoc> | ||
| + | == Heading 1 == | ||
| + | </ | ||
| + | |||
| + | Here's a Python script that could help with the conversion (only adds prefix; we'd need to modify it to add the suffix): | ||
| + | * https:// | ||
| + | |||
| + | |||
| + | ---- | ||
| + | |||
| + | ---- | ||
| + | |||
| + | |||
| ===== General ===== | ===== General ===== | ||
| Line 10: | Line 51: | ||
| ==== Headers ==== | ==== Headers ==== | ||
| * Headers should be in title case (i.e. capitalize important words) | * Headers should be in title case (i.e. capitalize important words) | ||
| - | * Headers can be formatted in either of two ways, but a single AsciiDoc file should use the same style consistently. | + | * Headers can be formatted in either of two ways, but a single AsciiDoc file should use the same style consistently. The prefered method is the Header Prefix Suffix format. |
| + | * Start all pages with Title 0. | ||
| === Changing A Section Heading === | === Changing A Section Heading === | ||
| Line 21: | Line 63: | ||
| **Header Prefix Syntax** | **Header Prefix Syntax** | ||
| < | < | ||
| - | == Header Level 1 | + | = Header Level 0 = |
| - | === Header Level 2 | + | == Header Level 1 == |
| - | ==== Header Level 3 | + | === Header Level 2 === |
| - | ===== Header Level 4 | + | ==== Header Level 3 ==== |
| + | ===== Header Level 4 ===== | ||
| </ | </ | ||
| **Header Underline Syntax** | **Header Underline Syntax** | ||
| < | < | ||
| + | Header Level 0 | ||
| + | ============== | ||
| Header Level 1 | Header Level 1 | ||
| -------------- | -------------- | ||
| Line 64: | Line 109: | ||
| * Use consistent action words | * Use consistent action words | ||
| * **Enter** a value into the text box | * **Enter** a value into the text box | ||
| - | * **Check** the check box if the situation applies | + | * **Check** or **Uncheck** the check box if the situation applies |
| * **Choose** or **Select** an option from the drop down menu | * **Choose** or **Select** an option from the drop down menu | ||
| * **Select** the button, tab or menu -> menu2 -> menu3 | * **Select** the button, tab or menu -> menu2 -> menu3 | ||
| Line 96: | Line 141: | ||
| * Syntax: '' | * Syntax: '' | ||
| * Example: | * Example: | ||
| - | * '' | + | * '' |
| * http:// | * http:// | ||
| * Add terms to the index | * Add terms to the index | ||
evergreen-docs/dig_style_guide.txt · Last modified: 2023/06/01 12:22 by gmcharlton