Docs: Make better use of UI style widgets #556

New Issue

basebuilder · 2024-01-28T12:39:49Z

basebuilder commented

2024-01-28 12:39:49 +00:00

The mkdocs-material framework and theme the docs site is using has some nice looking style widgets that we are currently not using. I think incorporating these into the site will raise the quality of readability and onboarding new Co-op Cloud users.

I post the snippets here for posterity and easy recall

Grid Cards

<div class="grid cards" markdown>

- :fontawesome-solid-earth-americas: __[Language]__ – Choose out of the 60+ supported languages or add a new one
- :material-page-layout-sidebar-left: __[Navigation]__ – Create a clear, concise, and comprehensive navigation structure
- :material-page-layout-header: __[Header]__ – Customize the behavior of the header, add an announcement bar
- :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer
- :material-tab-search: __[Search]__ – Set up and configure search, running entirely in the user's browser
- :material-tag-plus-outline: __[Tags]__ – Categorize your pages with tags and group related pages

</div>

Tasteful use of separators --- and __Bold Text__ in these cards also helps with nice clear delineation

<div class="grid cards" markdown>

-   :material-format-list-group: &nbsp; __[Built-in group plugin][group]__

    ---

    The group plugin allows to group plugins into logical units to conditionally
    enable or disable them for specific environments with the use of
    [environment variables][mkdocs.env].

    ---

    __Optimal management of plugins when building in different environments__

-   :material-file-tree: &nbsp; __[Built-in meta plugin][meta]__

    ---

    The meta plugin makes it easy to manage metadata (front matter) for all
    pages in a folder, so a certain subset of pages uses specific tags or a
    custom template.

    ---

    __Simpler organization, categorization and management of metadata__

Tabs

=== "Latest"

    ``` sh
    pip install mkdocs-material
    ```

=== "9.x"

    ``` sh
    pip install mkdocs-material=="9.*" # (1)!
    ```

The [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) framework and theme the docs site is using has some nice looking style widgets that we are currently not using. I think incorporating these into the site will raise the quality of readability and onboarding new Co-op Cloud users. I post the snippets here for posterity and easy recall --- **Grid Cards** ![Screenshot 2024-01-28 at 13-03-02 Setup - Material for MkDocs.png](/attachments/cffbf9d5-3304-41c5-a188-fb3244fc3e53) ``` <div class="grid cards" markdown> - :fontawesome-solid-earth-americas: __[Language]__ – Choose out of the 60+ supported languages or add a new one - :material-page-layout-sidebar-left: __[Navigation]__ – Create a clear, concise, and comprehensive navigation structure - :material-page-layout-header: __[Header]__ – Customize the behavior of the header, add an announcement bar - :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer - :material-tab-search: __[Search]__ – Set up and configure search, running entirely in the user's browser - :material-tag-plus-outline: __[Tags]__ – Categorize your pages with tags and group related pages </div> ``` Tasteful use of separators `---` and `__Bold Text__` in these cards also helps with nice clear delineation ![Screenshot 2024-01-28 at 13-34-12 Built-in plugins - Material for MkDocs.png](/attachments/66e95000-05b8-4242-93ba-6c11712b171c) ``` <div class="grid cards" markdown> - :material-format-list-group:   __[Built-in group plugin][group]__ --- The group plugin allows to group plugins into logical units to conditionally enable or disable them for specific environments with the use of [environment variables][mkdocs.env]. --- __Optimal management of plugins when building in different environments__ - :material-file-tree:   __[Built-in meta plugin][meta]__ --- The meta plugin makes it easy to manage metadata (front matter) for all pages in a folder, so a certain subset of pages uses specific tags or a custom template. --- __Simpler organization, categorization and management of metadata__ ``` **Tabs** ![Screenshot 2024-01-28 at 13-10-55 Installation - Material for MkDocs.png](/attachments/e8fd82cc-db0a-4168-add8-94009693586f) ``` === "Latest" ``` sh pip install mkdocs-material ``` === "9.x" ``` sh pip install mkdocs-material=="9.*" # (1)! ``` ```

Screenshot 2024-01-28 at 13-03-02 Setup - Material for MkDocs.png

62 KiB

Screenshot 2024-01-28 at 13-10-55 Installation - Material for MkDocs.png

53 KiB

Screenshot 2024-01-28 at 13-34-12 Built-in plugins - Material for MkDocs.png

72 KiB

👍 1

basebuilder added the

enhancement

documentation

design

labels 2024-01-28 12:39:49 +00:00

basebuilder self-assigned this 2024-01-28 12:39:49 +00:00

decentral1se commented

2024-01-28 19:54:01 +00:00

@basebuilder I feel like you might be the person to help with a docs re-shuffle?

Great taste on display so far! 😁

@basebuilder I feel like you might be the person to help with a docs re-shuffle? Great taste on display so far! 😁

🚀 1

basebuilder commented

2024-02-04 21:49:33 +00:00

@decentral1se I am getting the hang of the theme on the docs and i've started working on improving things. This is the sort of changes i'm making on my first style pass.

The current docs:

To my proposed changes:

@decentral1se I am getting the hang of the theme on the docs and i've started working on improving things. This is the sort of changes i'm making on my first style pass. The current docs: ![Screenshot 2024-02-04 at 22-44-47 Operators Guide - Co-op Cloud Public Interest Infrastructure.png](/attachments/11afa7bc-9260-45f1-8e65-ce998a8e109b) To my proposed changes: ![Screenshot 2024-02-04 at 22-46-34 Operators Guide - Co-op Cloud Public Interest Infrastructure.png](/attachments/d56d7b05-cff6-42ac-9012-70189e70713c)

Screenshot 2024-02-04 at 22-44-47 Operators Guide - Co-op Cloud Public Interest Infrastructure.png

63 KiB

Screenshot 2024-02-04 at 22-46-34 Operators Guide - Co-op Cloud Public Interest Infrastructure.png

71 KiB

❤️ 1

basebuilder referenced this issue from coop-cloud/docs.coopcloud.tech

2024-02-05 09:29:00 +00:00

style-widgets #245

basebuilder changed title from ~~Make better use of UI style widgets on Docs site~~ to Docs: Make better use of UI style widgets

2024-02-05 19:06:20 +00:00

basebuilder added this to the Improvements to Websites milestone 2024-02-06 11:06:07 +00:00

3wordchant commented

2024-02-10 20:27:28 +00:00

huge improvement, thank you!

❤️ 1

basebuilder commented

2024-02-21 20:22:16 +00:00

One thing i've been doing for #537 is making those info boxes (or annotations) collapsed by default, so instead of looking like this:

The inbox boxes looks like this:

Which does not interfere with flow of the tutorial as much.

One thing i've been doing for #537 is making those info boxes (or annotations) collapsed by default, so instead of looking like this: ![Screenshot 2024-02-06 at 00-05-54 New Operators Tutorial - Co-op Cloud Public Interest Infrastructure.png](/attachments/ddf0822c-2716-4c54-b795-967bb712a274) The inbox boxes looks like this: ![Screenshot 2024-02-21 at 21-20-01 New Operators Tutorial - Co-op Cloud Docs.png](/attachments/58219942-e1ca-4c55-a5d7-36ae4b3bf2f5) Which does not interfere with flow of the tutorial as much.

Screenshot 2024-02-06 at 00-08-54 New Operators Tutorial - Co-op Cloud Public Interest Infrastructure.png

43 KiB

Screenshot 2024-02-06 at 00-05-54 New Operators Tutorial - Co-op Cloud Public Interest Infrastructure.png

51 KiB

Screenshot 2024-02-21 at 21-20-01 New Operators Tutorial - Co-op Cloud Docs.png

24 KiB