Documentation Style Guide

Do's

• Use a GitHub Pull Request to submit documentation.
  • See the Editing Documentation documentation page for information on creating a Pull Request.
• Make it clear if the documentation is based on a particular configuration (such as the Install Profile Demo) or if it applies to any deployment of Islandora.

• Submit documentation formatted in Markdown format.

  • Include a top-level heading for the whole page (using #)
  • Please add Markdown headings (# and ##) to the content sections.

• Use the "bold/emphasis" style in Markdown by enclosing text in double asterisks or underscores, **bold text** or __bold text__, for UI elements that users will interact with. For example, a button label for a button that must be pressed should be made bold in Markdown.

• Use the "italics" style in Markdown by enclosing text in single asterisks or underscores, *italic text* or _italic text_, for UI elements that have a label or title if you need to reference them in the documentation. For example, a title of a screen or page that will visit should be made italic in Markdown.
• Use >> and **bold text** to indicate clicking through nested menu items, and also include the direct path. Example:

  **Administration** >> **Structure** >> **Views** (/admin/structure/views)
  

• Use - instead of * for bulleted lists. Indent four (4) spaces for nested lists (Github renders nesting in markdown with 2 spaces, but mkdocs needs 4). Example:

  - I am a list item
      - And I am a sub-item.
  

• Upload images to the 'assets' folder and reference them from there.
  • For file naming, use underscores between words and prefix all file names with the page name, e.g. context_display_hints.jpg for the image showing how to set display hints in the context menu.
• Use the Admonition syntax to create notes like this (four-space indent required):

Example:

!!! note "Helpful Tip"
    I am a helpful tip!

Result:

Helpful Tip

I am a helpful tip!

• Use our custom islandora type within the Admonition syntax to call attention to areas where Islandora configuration differs from standard Drupal configuration:

Example:

!!! islandora "Lobster trap"
    This setting is specific to Islandora and is not standard to Drupal.

Result:

Lobster trap

This setting is specific to Islandora and is not standard to Drupal.

Don'ts

• Do not leave any "trailing spaces" at the end of lines of content.
• Do not use "curly" quotes and apostrophes, use only "straight" quotes and apostrophes.
• Do not upload images that are excessively large in file size (remember, these docs are part of the software!)

---

Last update: September 25, 2024