Skip to content
Login This is a demo site for Change Maker. Learn more

# Authoring Content with Markdown and MkDocs Material

This guide provides a brief overview of writing content using Markdown and leveraging the styling capabilities of the MkDocs Material theme for your Changemaker documentation site.

## Markdown Basics

Markdown is a lightweight markup language with plain-text formatting syntax. It's designed to be easy to read and write.

### Headings

    # Heading 1
    ## Heading 2
    ### Heading 3

### Emphasis

    *Italic text* or _Italic text_
    **Bold text** or __Bold text__
    ~~Strikethrough text~~

### Lists

Ordered List:

    1. First item
    2. Second item
    3. Third item

Unordered List:

    - Item A
    - Item B
      - Sub-item B1
      - Sub-item B2
    * Item C

### Links

    [Link Text](https://www.example.com)
    [Link with Title](https://www.example.com "An example link")
    [Relative Link to another page](../apps/code-server.md)

### Images

    ![Alt text for image](/assets/images/changemaker.png "Optional Image Title")

Place your images in the `mkdocs/docs/assets/images/` directory (or create it if it doesn't exist) and reference them accordingly.

### Code Blocks

Inline Code: Use backticks: `this is inline code`.

Fenced Code Blocks (Recommended for multi-line code): Specify the language for syntax highlighting.

    ```python
    def hello_world():
      print("Hello, world!")
    ```

    ```html
    <h1>Hello</h1>
    ```

### Blockquotes

    > This is a blockquote.
    > It can span multiple lines.

### Horizontal Rule

    ---
    ***

### Tables

    | Header 1 | Header 2 | Header 3 |
    | :------- | :------: | -------: |
    | Align L  | Center   | Align R  |
    | Cell 1   | Cell 2   | Cell 3   |

## MkDocs Material Theme Features

MkDocs Material provides many enhancements and custom syntax options on top of standard Markdown.

### Admonitions (Call-outs)

These are great for highlighting information.

    !!! note
        This is a note.

    !!! tip "Optional Title"
        Here's a helpful tip!

    !!! warning
        Be careful with this action.

    !!! danger "Critical Alert"
        This is a critical warning.

    !!! abstract "Summary"
        This is an abstract or summary.

Supported types include: `note`, `abstract`, `info`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`.

### Code Blocks with Titles and Line Numbers

Your `mkdocs.yml` is configured for `pymdownx.highlight` which supports this.

    ```python title="my_script.py" linenums="1"
    print("Hello from Python")
    ```

### Emojis

Your `mkdocs.yml` has `pymdownx.emoji` enabled.

    :smile: :rocket: :warning:

See the MkDocs Material Emoji List for available emojis.

### Footnotes

Your `mkdocs.yml` has `footnotes` enabled.

    This is some text with a footnote.[^1]

    [^1]: This is the footnote definition.

### Content Tabs

Group related content under tabs.

    === "Tab 1 Title"
        Content for tab 1 (can be Markdown)

    === "Tab 2 Title"
        Content for tab 2

        ```python
        # Code blocks work here too
        print("Hello from Tab 2")
        ```

### Task Lists

    - [x] Completed task
    - [ ] Incomplete task
    - [ ] Another task

### Styling with Attributes (`attr_list`)

You can add CSS classes or IDs to elements.

    This is a paragraph with a custom class.
    {: .my-custom-class }

    ## A Heading with an ID {#custom-heading-id}

This is useful for applying custom CSS from your `extra.css` file.

### Buttons

MkDocs Material has a nice way to create buttons from links:

    [This is a button link](https://example.com){ .md-button }
    [Primary button](https://example.com){ .md-button .md-button--primary }
    [Another button](another-page.md){ .md-button }

## Editing Workflow

1. Use Code Server: Access Code Server from your Changemaker dashboard.
2. Navigate: Open the `mkdocs/docs/` directory.
3. Create or Edit: Create new `.md` files or edit existing ones.
4. Save: Save your changes (`Ctrl+S` or `Cmd+S`).
5. Preview:
   - If you have `mkdocs serve` running (either locally on your machine if developing there, or in a terminal within Code Server pointing to the `mkdocs` directory), your documentation site (usually at `http://localhost:8000` or `http://127.0.0.1:8000`) will auto-reload.
   - Alternatively, you can use VS Code extensions like "Markdown Preview Enhanced" within Code Server for a live preview pane.

## Further Reading

- MkDocs Material Reference: The official documentation for all features.
- Markdown Guide: For general Markdown syntax.

This guide should give you a solid start. Explore the MkDocs Material documentation for even more advanced features like diagrams, math formulas, and more complex page layouts.