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/12/04 16:42] – rjs7 | evergreen-docs:dig_style_guide [2021/10/27 15:50] – [Screenshots] jpringle | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== DIG AsciiDoc Style Guide (draft) | + | ====== DIG AsciiDoc Style Guide ====== |
- | ===== Proposal: Antora with Some AsciiDoc Changes ===== | + | ===== New AsciiDoc |
- | A small working group has been testing | + | As of the 3.6 release of Evergreen, we are using Antora as a new " |
- | In addition | + | In addition, |
==== 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 '' | + | This simply means adding this AsciiDoc line near the top of each '' |
- | <code asciidoc>: | ||
- | ==== Convert all headings from underline style to prefix/ | + | <code asciidoc> |
+ | : | ||
+ | |||
+ | |||
+ | |||
+ | ==== Use prefix/ | ||
The basic reasons are: | The basic reasons are: | ||
Line 35: | Line 39: | ||
* https:// | * https:// | ||
+ | ==== Changes to cross-reference structure ==== | ||
- | ---- | + | Antora requires a new cross-reference structure. All existing cross references were converted via script, but new docs will need to indicate cross references in this manner: |
+ | |||
+ | <code asciidoc> | ||
+ | xref: | ||
+ | </ | ||
+ | |||
+ | The above breaks down as follows: | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | For historical purposes, the old xref syntax is below | ||
+ | |||
+ | The below is an example of the now-deprecated cross reference style. **DO NOT USE THIS!** | ||
+ | <code asciidoc> | ||
+ | << | ||
+ | </ | ||
---- | ---- | ||
Line 51: | Line 74: | ||
==== 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. | + | * As noted above, the preferred Header format is the Header Prefix Suffix format. |
+ | * Start all pages with Title 0, followed by :toc: | ||
=== Changing A Section Heading === | === Changing A Section Heading === | ||
Line 62: | Line 86: | ||
**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 1 | + | As noted above, we are no longer using the header underline syntax as of the 3.6 documentation due to the Antora move. |
- | -------------- | + | |
- | Header Level 2 | + | |
- | ~~~~~~~~~~~~~~ | + | |
- | Header Level 3 | + | |
- | ^^^^^^^^^^^^^^ | + | |
- | Header Level 4 | + | |
- | ++++++++++++++ | + | |
- | </ | + | |
Line 90: | Line 107: | ||
* This allows AsciiDoc to auto-number the items as needed. | * This allows AsciiDoc to auto-number the items as needed. | ||
* **Ampersands** should be left as is (&). Don't use an HTML entity (which ironically causes errors in our HTML generator). | * **Ampersands** should be left as is (&). Don't use an HTML entity (which ironically causes errors in our HTML generator). | ||
+ | * If an ampersand appears in the staff client or OPAC use the ampersand in the documentation. | ||
* Any **code and command line commands** should be marked as +code+ or `code` | * Any **code and command line commands** should be marked as +code+ or `code` | ||
* If the code or command is hard to read when included in the paragraph, consider using a code block: | * If the code or command is hard to read when included in the paragraph, consider using a code block: | ||
Line 132: | Line 150: | ||
* Syntax: '' | * Syntax: '' | ||
* Example: | * Example: | ||
- | * Heading of "Create a provider" could be named '' | + | * Heading of "Creating Folders" |
* CAUTION: If you define an anchor that already exists, it will cause errors while building the HTML pages. If there are two sections with the same name, give them more specific names, like '' | * CAUTION: If you define an anchor that already exists, it will cause errors while building the HTML pages. If there are two sections with the same name, give them more specific names, like '' | ||
* LINK | * LINK | ||
- | * Syntax: '' | + | * Syntax: '' |
* Example: | * Example: | ||
- | * '' | + | * '' |
- | * http:// | + | |
* Add terms to the index | * Add terms to the index | ||
* Syntax: '' | * Syntax: '' | ||
Line 156: | Line 173: | ||
< | < | ||
- | .Use Case | + | Use Case |
************************************************ | ************************************************ | ||
This feature is useful in cases where | This feature is useful in cases where | ||
Line 169: | Line 186: | ||
* **Don' | * **Don' | ||
* **When replacing a screenshot**, | * **When replacing a screenshot**, | ||
+ | * Image syntax: '' | ||
+ | * Alt text: Please remember to include alt text in the image syntax 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, | ||
===== 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: | ||
* '' | * '' | ||
+ | * Callouts should be formatted as ''< | ||
+ | * Images, text blocks, or code blocks that are part of a numbered lists need to have a '' | ||
+ | |||
+ | <code asciidoc> | ||
+ | To edit a Receipt: | ||
+ | |||
+ | . Select *Administration -> Workstation -> Print Templates*. | ||
+ | . Choose the Receipt in the drop down list. | ||
+ | . If you are using Hatch, you can choose different printers for different types | ||
+ | of receipts with the Force Content field. If not, leave that field blank. | ||
+ | Printer Settings can be set at *Administration -> Workstation -> Printer | ||
+ | Settings*. | ||
+ | + | ||
+ | image:: | ||
+ | + | ||
+ | . Make edits to the Receipt on the right hand side. | ||
+ | </ | ||
+ | |||
+ | Note how this preserves the numbering: | ||
+ | |||
+ | {{: | ||
===== Further Reading ===== | ===== Further Reading ===== |
evergreen-docs/dig_style_guide.txt · Last modified: 2023/06/01 12:22 by gmcharlton