Writing with AsciiDoc
This training document will guide you through the basics of AsciiDoc, helping you create, format, and publish well-structured documents.
AsciiDoc
Most of the policy documents in PAMMS are written using AsciiDoc. AsciiDoc is a lightweight markup language that supports the structural and semantic elements necessary for writing web-first, technical content. It allows users to create structured policy documents.
Unlike traditional word processors, AsciiDoc focuses on simplicity and flexibility, enabling writers to concentrate on content while the formatting is standardized by the markup. This ensures that all the Policy documents have the same look and feel automatically.
The next section will detail the Standard Policy Document Structure and how each policy is set up. You can find examples of how to write in AsciiDoc below and the File Name guidelines.
File Names
A file’s name is used to create its page URL. Changing a file’s name will break links, cross-references (xrefs) in other files, and incoming links to the page from external websites.
When a file name is changed all cross-references (xrefs) links in all other policy files would need to be updated to the new name. This is why it is important that the file name be correct when initially created.
FILE NAME REQUIREMENTS:
-
Use all lowercase letters.
-
Do not use blank spaces. Separate words with hyphens.
-
Save AsciiDoc files with the .adoc extension.
-
Do not use symbols or special characters.
-
Do not include references to a version of the file in the File Name.
-
For example, 3000-v1.adoc or 3000-9-20-2024.adoc
-