User Tools

Site Tools


evergreen-docs:dig_style_guide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
evergreen-docs:dig_style_guide [2020/10/27 10:30] – [Common Mistakes] aneimanevergreen-docs:dig_style_guide [2023/06/01 12:22] (current) – update branch name from master to main gmcharlton
Line 9: Line 9:
 ==== 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> 
  
-==== Convert all headings from underline style to 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:
Line 44: Line 48:
  
 The above breaks down as follows: The above breaks down as follows:
-  * xref - indicates a cross reference +  * ''xref'' - indicates a cross reference 
-  * 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. **DO NOT USE THIS!** 
 <code asciidoc> <code asciidoc>
 <<reporter_creating_folders,Creating Folders>> <<reporter_creating_folders,Creating Folders>>
Line 63: Line 67:
 ===== General ===== ===== General =====
   * **Avoid changing section titles**. These are used to auto-generate anchor tags which are often used for links. Change with care, and check for links in other docs.   * **Avoid changing section titles**. These are used to auto-generate anchor tags which are often used for links. Change with care, and check for links in other docs.
-  * Always **review changes** before committing to master (and check the updated web page the next day to make sure it worked right). +  * Always **review changes** before committing to main (and check the updated web page the next day to make sure it worked right). 
-  * Always use **spell-check** on new content (including when porting old docs into master).+  * Always use **spell-check** on new content (including when porting old docs into main).
   * AsciiDoc code lines should be 80 characters long or shorter. (Occasionally, exceptions are necessary for correct syntax.)   * AsciiDoc code lines should be 80 characters long or shorter. (Occasionally, exceptions are necessary for correct syntax.)
   * Screenshots should be smaller than 1050 pixels wide (when possible).   * Screenshots should be smaller than 1050 pixels wide (when possible).
 +  * Rather than recreating documentation text in multiple adoc files, instead link directly to the main adoc for the feature. 
 ===== Formatting ===== ===== Formatting =====
 ==== Headers ==== ==== Headers ====
Line 103: Line 108:
     * 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.  In all other cases use the word 'and' instead of an ampersand. 
   * 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 181: Line 187:
   * **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::ascii_doc_name/imagename.png[alt text]''. Starting with version 3.8 screenshots should be put into folders with the same name as the page the images appear on.  For example, if your page is circulation_policies.adoc in the admin folder the image folder would be called circulation_policies and would be in admin -> assets -> images -> circulation_policies. 
 +  * 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, 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.
  
evergreen-docs/dig_style_guide.1603809042.txt.gz · Last modified: 2022/02/10 13:34 (external edit)

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.