Standard Policy Document Structure

A standard policy document, written with AsciiDoc is stored in the pages folder of a module. A policy document has a header, which includes the document title, and a body, which includes the content of the document that is displayed on the site.

Document title and header

The title of a document is placed on the first line of the file. It is specified by one equals sign (=), followed by one blank space, and then the text of the title. All documents stored in a pages folder must have a document title.

On the line directly below the title and subsequent contiguous lines, you will see several document attributes. Each attribute must be entered on its own line. These document attributes populate attribute references in the policy table.

Do not enter blank lines between the page title and the document attributes or between any of the attributes. The software considers the first blank line it encounters after the document title to indicate the end of the document header.

Policy document header structure
= 2835 AFDC Relatedness Budgeting (1)
:chapter-number: 2800 (2)
:effective-date: November 2020 (3)
:mt: MT-62
:policy-number: 2835
:policy-title: AFDC Relatedness Budgeting
:previous-policy-number: MT 45
(4)
include::partial$policy-header.adoc[] (5)

== Requirements

AFDC budgets are completed when determining eligibility under IV-E Foster Care.
1 Part of header. This is the title of the document. It is displayed at the top of the page on the site. It’s also displayed as the link text for the page in the navigation and any time an xref is created to the page and the link text in the xref macro is left empty. All policy documents must have a title.
2 Part of header. This is a document attribute. Its attribute name is chapter-number; its value, in this example, is 2800. This attribute is referenced in the policy-header.adoc partial (item 5 in this list) that is inserted into the document when the site is built. To learn more about this attribute and the other attributes present in the header of each document, see Attributes.
3 Part of header. This is a document attribute. effective-date behaves just like the other user-defined document attributes in this header.
4 Ends header. The document header ends with a blank line. This blank line tells the software that the lines following this blank line should be treated as the body of the policy document.
5 Part of body. This is an include directive that inserts the contents of the policy-header.adoc file as the first content on the page, following the policy title. The policy-header.adoc file is a table presenting the key information about each policy. This table is set up as a partial so that every document has the same table layout and formatting. That is, the table only had to be created once (versus every person having to create and maintain the table in every document). The software uses the document attributes in the header of each policy to populate the cells in the table that reference the attributes when the site is built.

Document sections

A document is divided into sections by heading titles. Heading 2 section titles, indicated by two equals signs (==), are displayed in the Contents sidebar.

Section heading syntax
== Heading 2 Section Title (H2)

Content in section.

=== Heading 3 Section Title (H3)

Content in section.

==== Heading 4 Section Title (H4)

Content in section.

===== Heading 5 Section Title (H5)

Content in section.

Don’t nest sections out of order. For example, a heading 4 section can’t be directly inside a heading 2 section; it must be nested inside a heading 3 section.

Don’t apply bold, italic, or underline formatting to section headings unless you feel it is absolutely necessary. The styling of the headings is handled by the site’s user interface (also referred to as the UI or stylesheet) when the site is generated and published.

Policy body and section structure
= 2835 AFDC Relatedness Budgeting
:chapter-number: 2800
:effective-date: November 2020
:mt: MT-62
:policy-number: 2835
:policy-title: AFDC Relatedness Budgeting
:previous-policy-number: MT 45
(1)
include::ROOT:partial$policy-header.adoc[] (2)
 (3)
== Requirements (4)
(5)
AFDC budgets are completed when determining eligibility under IV-E Foster Care. (6)
(7)
== Basic Considerations (8)

The AFDC Budget is based on the circumstances in the home from which the child was removed.
1 Ends header. Make sure there is a blank line separating your document header from the body content of your document. The document body starts on next line that has text. In this example, that text is an include directive that inserts the policy-header.adoc file.
2 Part of body. This is an include directive that inserts the contents of the policy-header.adoc file as the first content on the page, following the policy title. Its contents are described in more detail in the previous example.
3 Part of body. In general, you want to separate block elements (e.g., section headings, paragraphs, image block macros, etc.) with a blank line.
4 Part of body. This is a heading 2 section title. A heading 2 section title is created by typing two equals signs (==) at the beginning of a new line, followed by a space, and then the title of the section. At the end of the section title, press Enter once to go to a new line, and then press Enter again. The heading is styled by the site’s UI when the site is generated and published; therefore, we don’t recommend adding additional formatting such as bold, italic, or underline styling to your section headings. The text of heading 2 section titles is displayed on the right side of the page, in the Contents sidebar.
5 Part of body. After each section heading, make sure there is a blank line between the heading and the next block of content.
6 Part of body. The most common content in the body of a document are paragraphs. There’s no special syntax for a paragraph in AsciiDoc. Just start typing at the start of a new line. To separate paragraphs, make sure to enter a blank line between them. AsciiDoc considers paragraph content (e.g., regular text, sentences, phrases) that are on contiguous adjacent lines to be part of the same paragraph. See Ventilated prose (aka sentence per line) for more information.
7 Part of body. At the end of the content in a section, insert a blank line before starting a new section with a section header.
8 Part of body. This is a heading 2 section title.

Ventilated prose (aka sentence per line)

Sentences that are part of paragraphs, lists, and tables can be entered on individual lines. This recommended practice makes reviewing merge requests and comparing versions of the same file much easier for maintainers. It’s also helpful for identifying very long sentences that might benefit from being split up or edited. However, ventilated prose isn’t required.

Filename and format extension

  • Use all lowercase letters.

  • Separate words with hyphens.

  • Save AsciiDoc files with the .adoc extension.

  • Don’t use symbols or special characters.

The file’s name is used to create its page URL. Changing a file’s name will break cross references (xrefs) and incoming links to the page from external websites.