Skip to content

Documentation

In addition to welcoming code contributions, we also welcome improvements and additions to this documentation site.

This site is built with Material for MkDocs and some additional plugins; the content is written primarily in Markdown.

About the documentation#

Throughout this docuemtation site, we try to closely follow this theory of documentation which organizes docs along two axes:

  1. theoretical vs. practical
  2. study-oriented vs. work-oriented

From the quadrants of this breakdown, we have four different types of documentation:

As we write documentation, we try to tag and organize it in these categories. (Click the buttons above to view pages with the corresponding tag.)

Documentation feature reference#

The rest of this page highlights some advanced features of Material for MkDocs which you may use to make the docs more visually appealing.

Snippets#

Make reusable markdown snippets by defining a file in the snippets/ folder and add it into your markdown with

--8<-- "snippets/file.md"

Some snippets we have currently available include

  • Stylized edu (snippets/edu.md): edu 

    --8<-- "snippets/edu.md"

  • Stylized enable data union (snippets/enable_data_union.md): enable data union 

    --8<-- "snippets/enable_data_union.md"

  • Current edu version (snippets/current_version.md): 0.1.0 

    --8<-- "snippets/current_version.md"

Tabbed code blocks#

Code like this 

=== "PostgreSQL"
    ``` sql
    select
      people.json_data->>'phone'->>'mobile' as mobile_phone
    from people
    ```

=== "Snowflake"
    ``` sql
    select
      get( get( parse_json( people.json_data ), 'phone'), 'mobile') as mobile_phone
    from people
    ```

produces tabbed code blocks like this

select
  people.json_data->>'phone'->>'mobile' as mobile_phone
from people

select
  get( get( parse_json( people.json_data ), 'phone'), 'mobile') as mobile_phone
from people

Call-to-action buttons#

[Subscribe to our newsletter](#){ .md-button .md-button--primary }

produces a nice button like

Subscribe to our newsletter

Data tables#

Markdown code for nice-looking tables is like this

| Table                                  | Grain                                        | Notes                                |
| -------------------------------------- | -------------------------------------------- | ------------------------------------ |
| `fct_student_daily_attendance`         | `student`, `school`, `calendar_date`         | Positive attendance is inferred      |
| `fct_student_school_attendance_event`  | `student`, `school`, `calendar_date`         | May contain only negative attendance |
| `fct_student_section_attendance_event` | `student`, `course_section`, `calendar_date` | May contain only negative attendance |

producing

Table Grain Notes
fct_student_daily_attendance student, school, calendar_date Positive attendance is inferred
fct_student_school_attendance_event student, school, calendar_date May contain only negative attendance
fct_student_section_attendance_event student, course_section, calendar_date May contain only negative attendance

Emojis 😄#

C'mon man, who doesn't want access to 8,000+ icons? 😆 🧑‍🏫 🧑‍🎓 🏫 📚 ❤

:laughing: :teacher: :student: :school: :books: :heart:

Footnotes#

Scientific studies[^1] show that Markdown documentation is awesome!

[^1]: [Science](https://en.wikipedia.org/wiki/Science) is a systematic enterprise that builds and organizes knowledge in the form of testable explanations and predictions.

produces

Scientific studies1 show that Markdown documentation is awesome!

LaTeX (math) expressions#

$$
E = m \cdot c^2
$$

produces

\[ E = m \cdot c^2 \]

Tooltips#

Tooltips like this are possible with Markdown code like

:material-information-outline:{ title="Important information" }

Admonitions#

Draw attention to content using Admonitions. Code like this

!!! tip "Tip of the Day"

    A truly excellent product sparks joy for the user. It delights them with beauty and thoughtfulness, belying the creator's anticipation of the user's needs and desires; the care and empathy, craft and effort put in to build something simply wonderful.

produces

Tip of the Day

A truly excellent product sparks joy for the user. It delights them with beauty and thoughtfulness, belying the creator's anticipation of the user's needs and desires; the care and empathy, craft and effort put in to build something simply wonderful.

Here's another example:

??? note "Collapsible note"

    There are lots of different admonition [types](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types) (`note`, `summary`, `info`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, and `quote`) and other options. See [the docs here](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage).
Collapsible note

There are lots of different admonition types (note, summary, info, tip, success, question, warning, failure, danger, bug, example, and quote) and other options. See the docs here.

  1. Science is a systematic enterprise that builds and organizes knowledge in the form of testable explanations and predictions. ↩