Skip to content

Latest commit

 

History

History
184 lines (119 loc) · 4.01 KB

formatting.md

File metadata and controls

184 lines (119 loc) · 4.01 KB
Raw

Formatting content

Tables

Introduce the table with a sentence. For example, “The following table lists which operations must be made available to a developer accessing a Knative Route using a minimal profile.”

Markdown table template

|Header 1|Header 2|
|--------|--------|
|Data1   |Data2   |
|Data3   |Data4   |

Ordered lists

Write a sentence or two to introduce the content of the list. For example, “If you want to fix or add content to a past release, you can find the source files in the following folders.”. Optionally, include bold lead-ins before each list item.

NOTE: For the formatting to render correctly, you must add an empty line between the list and the preceding sentence.

Markdown ordered list template

Introductory sentence:

1. Item 1
1. Item 2
1. Item 3

Introductory sentence:

1. **Lead-in description:** Item 1
1. **Lead-in description:** Item 2
1. **Lead-in description:** Item 3

Nested ordered lists template

For formatting to render correctly, nested items must be indented by four spaces in relation to their parent item.

Introductory sentence:

1. Item 1

    1. Item 1a

1. Item 2

Unordered Lists

Write a sentence or two to introduce the content of the list. For example, “Your own path to becoming a Knative contributor can begin in any of the following components:”. Optionally, include bold lead-ins before each list item.

NOTE: For the formatting to render correctly, you must add an empty line between the list and the preceding sentence.

Markdown unordered list template

Introductory sentence:

* List item
* List item
* List item

Introductory sentence:

* **Lead-in**: List item
* **Lead-in**: List item
* **Lead-in**: List item

Nested unordered list template

Nested items must be indented by four spaces in relation to their parent item.

Introductory sentence:

* List item

    * List sub-item

* List item

Documenting code and code snippets

For instructions on how to format code and code snippets, see the Style guide.

Content Tabs

Content tabs are handy way to organize lots of information in a visually pleasing way. Place multiple versions of the same procedure (such as a kn CLI procedure vs a YAML procedure) within tabs. Indent the tab content by four spaces to make the tabs display properly.

For example:

== "tab1 name"

    This is a stem:

    1. This is a step.

      ```
      This is some code.
      ```

    1. This is another step.

== "tab2 name"

    This is a stem:

    1. This is a step.

      ```
      This is some code.
      ```

    1. This is another step.

For more information, see the Material for MkDocs documentation

Admonitions

We use the note, tip, and warning admonition boxes only. Use admonitions sparingly; too many admonitions can be distracting. The formatting for notes is as follows:

Notes

!!! note
    A Note contains information that is useful, but not essential.
    A reader can skip a note without bypassing required information.
    If the information suggests an action to take, use a tip instead.

Tips

!!! tip
    A Tip suggests a helpful, but not mandatory, action to take.

Warnings

!!! warning
    A Warning draws attention to potential trouble.

Icons and Emojis

Material for MkDocs supports using Material Icons and Emojis using easy shortcodes. For example, the taco emoji 🌮, is formatted as :taco:.

To search a database of Icons and Emojis (all of which can be used on Knative.dev), as well as usage information, see the Material for MkDocs documentation

TODO (Add Requests Here)

  • Navigation using lukasgeiter/mkdocs-awesome-pages-plugin: An MkDocs plugin that simplifies configuring page titles and their order
  • Index.md vs. README.md
  • awesome-pages