https://raw.githubusercontent.com/adventuregamestudio/ags-manual/2aed2f7033bc93fc170c132cd69cc0ed48899129/README.md

Need to add to this document a reference on how Headings works.

When the page metadata is built it checks level 2 headers to to use a section title, and then level 3 as a subsection. Unless the level 2 header is determined to be a script API tile, then the level 3 header is appended as a member.

So:

## Object functions and properties
### ID

Would give you index entries for Object and Object.ID

## Getting Started
### Installing

Would give you index entries for Getting Started and Installing

For purposes of spell checking, I think that the only way it can manageable is to strip out code and author/copyright notices and run the spell check against the remainder of the page.

For this to work anything that is script needs to be in an inline script element or

a block
script
element

For credits and copyright notices, probably the best thing to use is:

a block
quote
element

This would be great to add here: https://github.com/adventuregamestudio/ags-manual/blob/master/CONTRIBUTING.md

Unfortunately I don't have much idea of the format "rules" other than observing how things are currently and trying to match...

@morganwillcock is there any details on particular behaviors / relationship with the index that is necessary to note here?

Started to write it here: https://gist.github.com/ericoporto/895cbe102fac2d896fdd4bc03ba6374c#file-format-md

Found some resources, but if someone knows one more concise and useful from other project, please tell below

• https://github.com/google/styleguide/blob/gh-pages/docguide/style.md
• https://learn.microsoft.com/en-us/style-guide/procedures-instructions/formatting-text-in-instructions?source=recommendations
• https://experienceleague.adobe.com/docs/contributor/contributor-guide/writing-essentials/markdown.html?lang=en

@morganwillcock is there any details on particular behaviors / relationship with the index that is necessary to note here?

The main thing to set which determines the index content is whether an item relates to the script API or not. In headings it takes the first inline code item as the name of whatever should be indexed.

printf '## `Character` functions and properties\n### `Character.AddInventory`' \
    | pandoc -t lua/write_metablock.lua

-- nil

return {
  ["links"] = {
  },
  ["keywords"] = {
    ["properties"] = 1,
    ["functions"] = 1,
    ["Character"] = 2,
    ["AddInventory"] = 1,
  },
  ["index"] = {
    [2] = {
      ["itemtype"] = "script",
      ["id"] = "character.addinventory",
      ["header"] = "Character.AddInventory",
    },
    [1] = {
      ["itemtype"] = "script",
      ["id"] = "character-functions-and-properties",
      ["header"] = "Character",
    },
  },
}

Marking something as code records that the index type is "script" and uses the inline code text for the index entry, for both the CHM file and the web index these are displayed at the top level of the index.

Character
Character.ActiveInventory

...for the CHM file it cannot be anywhere else because the editor tries to find script documentation at the top level of the index.

Not marking something as code stores the index type as "editorial" (I couldn't think of a better name at the time, it is meant to be other content in the manual) and the normal heading name is used for the index entry.

printf '## Character functions and properties\n### Character.AddInventory' \
    | pandoc -t lua/write_metablock.lua

-- nil

return {
  ["links"] = {
  },
  ["keywords"] = {
    ["properties"] = 1,
    ["functions"] = 1,
    ["Character"] = 2,
    ["AddInventory"] = 1,
  },
  ["index"] = {
    [2] = {
      ["itemtype"] = "editorial",
      ["id"] = "character.addinventory",
      ["header"] = "Character.AddInventory",
    },
    [1] = {
      ["itemtype"] = "editorial",
      ["id"] = "character-functions-and-properties",
      ["header"] = "Character functions and properties",
    },
  },
}

The CHM file and web index differ here, but the goal is to avoid name collisions between top level index items. For the CHM file the page title is at the top level of the index and the other index entries are added as sub-entries:

Character functions and properties
   Character.ActiveInventory

The web index appends the page title to the other index entries and is just a flat list:

Character.ActiveInventory (Character functions and properties)

So in both cases there are only two levels. The page title is taken from the first level 2 heading on the page if it isn't explicitly set.

In summary:

• all headings that document the script API need to have the script syntax marked as code and have unique names
• all headings that are used for general documentation need to use a level 2 heading that doesn't collide with script syntax or level 2 headings on any other general documentation page
• within a single page all headings names need to be unique