Skip to content

docs(deps): bump mkdocs-material to v8.2.1#2422

Merged
wernerfred merged 4 commits intomasterfrom
upgrade/mkdocs-8-2-1
Feb 19, 2022
Merged

docs(deps): bump mkdocs-material to v8.2.1#2422
wernerfred merged 4 commits intomasterfrom
upgrade/mkdocs-8-2-1

Conversation

@wernerfred
Copy link
Copy Markdown
Member

@wernerfred wernerfred commented Feb 18, 2022

Description

This will upgrade mkdocs-material to v8.2.1 which just hit a new milestone

We now can:

  • Added native support for Mermaid.js diagrams
  • Added native support for tags (with search integration)
  • Added support for staying on page when switching versions

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Improvement (non-breaking change that does improve existing functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation (README.md or the documentation under docs/)
  • If necessary I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes

@wernerfred wernerfred self-assigned this Feb 18, 2022
@polarathene
Copy link
Copy Markdown
Member

polarathene commented Feb 19, 2022 •
edited
Loading

EDIT: I added the changes myself. Hope you don't mind :)

It seems to render the fenced codebock of mermaid markdown until JS kicks in to convert to mermaid flowchart graphic. In most cases that shouldn't be a problem I think.

With the mermaid.js integration we can update this page now:

docker-mailserver/docs/content/config/security/understanding-the-ports.md

Lines 22 to 55 in f97fa26

### What Ports Should I Use? (SMTP)
[![Best Practice - Ports (SMTP)][asset-external-mermaid-smtp]][ref-mermaid-live-smtp]
??? "Flowchart - Mermaid.js source:"
View in the [Live Editor][ref-mermaid-live-smtp].
```mermaid
flowchart LR
subgraph your-server ["Your Server"]
in_25(25) --> server
in_465(465) --> server
server(("docker-mailserver<br/>[email protected]"))
server --- out_25(25)
server --- out_465(465)
end
third-party("Third-party<br/>(sending you email)") ---|"Receive email for<br/>[email protected]"| in_25
subgraph clients ["Clients (MUA)"]
mua-client(Thunderbird,<br/>Webmail,<br/>Mutt,<br/>etc)
mua-service(Backend software<br/>on another server)
end
clients ---|"Send email as<br/>[email protected]"| in_465
out_25(25) -->|"Direct<br/>Delivery"| tin_25
out_465(465) --> relay("MTA<br/>Relay Server") --> tin_25(25)
subgraph third-party-server["Third-party Server"]
third-party-mta("MTA<br/>[email protected]")
tin_25(25) --> third-party-mta
end
```

The first few lines (externally linked image, live editor link, admonition) can all be dropped, with indentation for the admonition content dropped (along with the two associated links referenced at bottom of the markdown document):

[![Best Practice - Ports (SMTP)][asset-external-mermaid-smtp]][ref-mermaid-live-smtp]

??? "Flowchart - Mermaid.js source:"

    View in the [Live Editor][ref-mermaid-live-smtp].

The docs preview I linked to shows that it's not rendering quite the same. Seems we'd have to extract some CSS for that maybe, probably not worth the effort, still serves the intended purpose 😅

polarathene
polarathene previously approved these changes Feb 19, 2022
View reviewed changes
@polarathene
chore: Adopt mkdocs-material mermaid integration support
b93ee11 
Supported by the docs generator now, we no longer need to rely on external image generator or live editor link (both relied on large base64 encoding of mermaid markup). SVG will be rendered by docs now, although a little different style (can be fixed with custom CSS).
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 19, 2022

Documentation preview for this PR is ready! 🎉

Built with commit: b93ee11

@wernerfred wernerfred marked this pull request as ready for review February 19, 2022 07:15
@wernerfred
Copy link
Copy Markdown
Member Author

wernerfred commented Feb 19, 2022

Thx

georglauterbach
georglauterbach approved these changes Feb 19, 2022
View reviewed changes
Copy link
Copy Markdown
Member

@georglauterbach georglauterbach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@wernerfred wernerfred merged commit 358df6a into master Feb 19, 2022
@wernerfred wernerfred deleted the upgrade/mkdocs-8-2-1 branch February 19, 2022 20:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@casperklein casperklein casperklein approved these changes

@polarathene polarathene polarathene approved these changes

@georglauterbach georglauterbach georglauterbach approved these changes

Assignees

@wernerfred wernerfred

Labels

area/ci area/configuration (file) area/documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@wernerfred @polarathene @casperklein @georglauterbach