Troubleshooting Knowledge Hub formatting

This is a catalogue of known issues and solutions for converting notebooks to html with Sphinx See Sphinx documentation for some guidelines around how markdown in notebooks converts to html.

Bullets

Bullets not displaying correctly

Check that there is an empty line before your bullet list

My list:

* one
* two

as opposed to

My list:
* one
* two

Check that you have used * to mark bullets, rather than -

My list:

* one
* two

as opposed to

My list:

- one
- two

Check that sub-lists are indented by four spaces, rather than two

My list:

* one
    * two
    * three
* four

as opposed to

My list:

* one
  * two
  * three
* four

Text formatting

Text displays strangely

Examples

• Products used: ga_ls5t_ard_3 <https://explorer.sandbox.dea.ga.gov.au/ga_ls5t_ard_3>__
• Notebook currently compatible with both the NCI and DEA Sandbox environments

Solution: check whether there are two kinds of formatting and reduce it to one.

Examples

• ga_ls56_ard_3 rather than ga_ls5_ard_3
• Compatible with NCI rather than Compatible with NCI

Disappearing headers

Headers must be initially in ascending order of # symbols to display correctly. Headers should always be directly nested: Title, then subheading, then sub-subheading, before going back up to a new sub heading. There can only be one entry with the highest-level # heading; this is typically reserved for the notebook title.

# Title

## Subheading 1

### Sub-subheading 1

#### Sub-sub-subheading 1

## Subheading 2

etc

As opposed to

# Title

### Sub-subheading 1

## Subheading 1

#### Sub-sub-subheading 1

## Subheading 2

etc

Alert boxes

To ensure that an alert box displays correctly on the Knowledge Hub as well as the DEA Sandbox, you must use the specific formatting below. There must be blank lines separating the 'div' tags from the content, and Markdown must be used inside the 'div'. (If you don't follow this exact format, the alert box could be stripped of formatting and HTML tags on the Knowledge Hub.)

<div class="alert alert-info">

**Note:** Visit the [DEA Intertidal product description](https://knowledge.dea.ga.gov.au/notebooks/DEA_products/DEA_Intertidal/) for technical information about DEA Intertidal including a comprehensive review of the methods employed in the generation of datasets in this product suite.

</div>

This will display as follows.