Changemaker/mkdocs/docs/guides/authoring-content.md

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.