Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix(website): Use native Mermaid, refactor contribution docs #3177

Closed
wants to merge 1 commit into from
Closed

fix(website): Use native Mermaid, refactor contribution docs #3177

wants to merge 1 commit into from

Conversation

bradenhilton
Copy link
Collaborator

Fixes #3175

Without this change (chezmoi.io):

Screen Shot 2023-08-16 at 14 20 30

With this change (working copy):

Screen Shot 2023-08-16 at 14 19 41

@bradenhilton
Copy link
Collaborator Author

bradenhilton commented Aug 16, 2023 •
edited
Loading

mkdocs serve gives this output:

Output 
❯ mkdocs serve
INFO    -  Building documentation...
template: articles.md.tmpl:9:22: executing "articles.md.tmpl" at <.articles>: can't evaluate field articles in type string
exit status 1
template: podcasts.md.tmpl:9:22: executing "podcasts.md.tmpl" at <.articles>: can't evaluate field articles in type string
exit status 1
template: videos.md.tmpl:9:22: executing "videos.md.tmpl" at <.articles>: can't evaluate field articles in type string
exit status 1
INFO    -  Cleaning site directory
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - reference\templates\doppler\index.md
             - reference\templates\doppler\doppler.md
             - reference\templates\doppler\dopplerProjectJson.md
             - user-guide\password-managers\doppler.md
WARNING -  A relative path to 'reference/templates/doppler-functions/index.md' is included in the 'nav' configuration,
           which is not found in the documentation files.
WARNING -  A relative path to 'reference/templates/doppler-functions/doppler.md' is included in the 'nav' configuration,
           which is not found in the documentation files.
WARNING -  A relative path to 'reference/templates/doppler-functions/dopplerProjectJson.md' is included in the 'nav'
           configuration, which is not found in the documentation files.
WARNING -  A relative path to 'links/articles.md' is included in the 'nav' configuration, which is not found in the
           documentation files.
WARNING -  A relative path to 'links/podcasts.md' is included in the 'nav' configuration, which is not found in the
           documentation files.
WARNING -  A relative path to 'links/videos.md' is included in the 'nav' configuration, which is not found in the
           documentation files.
INFO    -  Doc file 'index.md' contains an absolute link '/reference/release-history', it was left as is. Did you mean
           'reference/release-history.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/install/', it was left as is. Did you mean 'install.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/install/', it was left as is. Did you mean 'install.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/quick-start/', it was left as is. Did you mean
           'quick-start.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/user-guide/setup/', it was left as is. Did you mean
           'user-guide/setup.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/reference/', it was left as is. Did you mean
           'reference/index.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/links/articles', it was left as is.
INFO    -  Doc file 'index.md' contains an absolute link '/links/podcasts', it was left as is.
INFO    -  Doc file 'index.md' contains an absolute link '/links/videos', it was left as is.
INFO    -  Doc file 'index.md' contains an absolute link '/comparison-table/', it was left as is. Did you mean
           'comparison-table.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/links/dotfile-repos/', it was left as is. Did you mean
           'links/dotfile-repos.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/links/social-media/', it was left as is. Did you mean
           'links/social-media.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/links/dotfile-repos/', it was left as is. Did you mean
           'links/dotfile-repos.md'?
INFO    -  Doc file 'index.md' contains an absolute link '/developer/contributing-changes/', it was left as is. Did you
           mean 'developer/contributing-changes.md'?
INFO    -  Doc file 'install.md' contains an absolute link '/reference/release-history', it was left as is. Did you mean
           'reference/release-history.md'?
INFO    -  Doc file 'install.md' contains an absolute link '/developer/releases/', it was left as is. Did you mean
           'developer/releases.md'?
INFO    -  Doc file 'quick-start.md' contains an absolute link '/reference/concepts/', it was left as is. Did you mean
           'reference/concepts.md'?
INFO    -  Doc file 'quick-start.md' contains an absolute link '/install/', it was left as is. Did you mean
           'install.md'?
INFO    -  Doc file 'quick-start.md' contains an absolute link
           '/user-guide/frequently-asked-questions/usage/#how-do-i-edit-my-dotfiles-with-chezmoi', it was left as is.
           Did you mean 'user-guide/frequently-asked-questions/usage.md#how-do-i-edit-my-dotfiles-with-chezmoi'?
INFO    -  Doc file 'quick-start.md' contains an absolute link '/links/articles/', it was left as is.
INFO    -  Doc file 'quick-start.md' contains an absolute link '/user-guide/setup/', it was left as is. Did you mean
           'user-guide/setup.md'?
INFO    -  Doc file 'quick-start.md' contains an absolute link '/links/dotfile-repos/', it was left as is. Did you mean
           'links/dotfile-repos.md'?
INFO    -  Doc file 'developer/architecture.md' contains an absolute link '/reference/concepts/', it was left as is. Did
           you mean '../reference/concepts.md'?
INFO    -  Doc file 'developer/contributing-changes.md' contains an absolute link '/developer/website/', it was left as
           is. Did you mean 'website.md'?
INFO    -  Doc file 'developer/packaging.md' contains an absolute link '/install/', it was left as is. Did you mean
           '../install.md'?
INFO    -  Doc file 'reference/command-line-flags/global.md' contains an absolute link '/reference/configuration-file',
           it was left as is. Did you mean '../configuration-file/index.md'?
INFO    -  Doc file 'reference/commands/add.md' contains an absolute link
           '/reference/special-files-and-directories/chezmoiexternal-format/', it was left as is. Did you mean
           '../special-files-and-directories/chezmoiexternal-format.md'?
INFO    -  Doc file 'reference/special-files-and-directories/chezmoiexternal-format.md' contains an absolute link
           '/user-guide/include-files-from-elsewhere/', it was left as is. Did you mean
           '../../user-guide/include-files-from-elsewhere.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/doctor/', it was
           left as is. Did you mean '../reference/commands/doctor.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/init/', it was left
           as is. Did you mean '../reference/commands/init.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/add/', it was left
           as is. Did you mean '../reference/commands/add.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/edit/', it was left
           as is. Did you mean '../reference/commands/edit.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/status/', it was
           left as is. Did you mean '../reference/commands/status.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/diff/', it was left
           as is. Did you mean '../reference/commands/diff.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/apply/', it was left
           as is. Did you mean '../reference/commands/apply.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/edit/', it was left
           as is. Did you mean '../reference/commands/edit.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/cd/', it was left as
           is. Did you mean '../reference/commands/cd.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/init/', it was left
           as is. Did you mean '../reference/commands/init.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/init/', it was left
           as is. Did you mean '../reference/commands/init.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/update/', it was
           left as is. Did you mean '../reference/commands/update.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/data/', it was left
           as is. Did you mean '../reference/commands/data.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/add/', it was left
           as is. Did you mean '../reference/commands/add.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/chattr/', it was
           left as is. Did you mean '../reference/commands/chattr.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/cat/', it was left
           as is. Did you mean '../reference/commands/cat.md'?
INFO    -  Doc file 'user-guide/command-overview.md' contains an absolute link '/reference/commands/execute-template/',
           it was left as is. Did you mean '../reference/commands/execute-template.md'?
INFO    -  Doc file 'user-guide/daily-operations.md' contains an absolute link '/reference/commands/init/', it was left
           as is. Did you mean '../reference/commands/init.md'?
INFO    -  Doc file 'user-guide/include-files-from-elsewhere.md' contains an absolute link
           '/reference/special-files-and-directories/chezmoiexternal-format/', it was left as is. Did you mean
           '../reference/special-files-and-directories/chezmoiexternal-format.md'?
INFO    -  Doc file 'user-guide/manage-machine-to-machine-differences.md' contains an absolute link
           '/reference/templates/functions/', it was left as is. Did you mean
           '../reference/templates/functions/index.md'?
INFO    -  Doc file 'user-guide/templating.md' contains an absolute link '/reference/templates/functions/', it was left
           as is. Did you mean '../reference/templates/functions/index.md'?
INFO    -  Doc file 'user-guide/templating.md' contains an absolute link '/reference/templates/variables/', it was left
           as is. Did you mean '../reference/templates/variables.md'?
INFO    -  Doc file 'user-guide/advanced/migrate-away-from-chezmoi.md' contains an absolute link
           '/reference/commands/purge/', it was left as is. Did you mean '../../reference/commands/purge.md'?
INFO    -  Doc file 'user-guide/advanced/migrate-away-from-chezmoi.md' contains an absolute link
           '/reference/commands/archive/', it was left as is. Did you mean '../../reference/commands/archive.md'?
INFO    -  Doc file 'user-guide/advanced/migrate-away-from-chezmoi.md' contains an absolute link
           '/reference/commands/dump/', it was left as is. Did you mean '../../reference/commands/dump.md'?
INFO    -  Doc file 'user-guide/frequently-asked-questions/design.md' contains an absolute link
           '/reference/target-types/#symlink-mode', it was left as is. Did you mean
           '../../reference/target-types.md#symlink-mode'?
INFO    -  Doc file 'user-guide/frequently-asked-questions/general.md' contains an absolute link
           '/links/articles-podcasts-and-videos/', it was left as is.
INFO    -  Doc file 'user-guide/frequently-asked-questions/general.md' contains an absolute link
           '/developer/contributing-changes/', it was left as is. Did you mean
           '../../developer/contributing-changes.md'?
INFO    -  Doc file 'user-guide/frequently-asked-questions/troubleshooting.md' contains an absolute link '/install/', it
           was left as is. Did you mean '../../install.md'?
INFO    -  Doc file 'user-guide/frequently-asked-questions/usage.md' contains an absolute link
           '/reference/special-files-and-directories/chezmoiignore/', it was left as is. Did you mean
           '../../reference/special-files-and-directories/chezmoiignore.md'?
INFO    -  Doc file 'user-guide/frequently-asked-questions/usage.md' contains an absolute link
           '/user-guide/daily-operations/#automatically-commit-and-push-changes-to-your-repo', it was left as is. Did
           you mean '../daily-operations.md#automatically-commit-and-push-changes-to-your-repo'?
INFO    -  Documentation built in 26.70 seconds
INFO    -  [14:41:08] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [14:41:08] Serving on http://127.0.0.1:8000/

which I can't recall seeing the last time I contributed to the website, but I'm not sure how it impacts anything as it does successfully build, and everything appears to be in order after a cursory look.

@bradenhilton
Copy link
Collaborator Author

I've encountered a few issues debugging the output. I'll open a new issue so they can be resolved first.

This was referenced Aug 16, 2023
Closed
Closed
@twpayne
Copy link
Owner

twpayne commented Aug 21, 2023

@bradenhilton Is this superseded by #3181?

@bradenhilton
Copy link
Collaborator Author

@twpayne Partially.

Aside from the (now outdated) contribution steps change, this just removes mkdocs-mermaid2-plugin in favor of the native implementation, which does look slightly different on the page by default.

You can close for now if you'd like, I'll update the PR and switch it to chore in case we want to revisit later.

@bradenhilton bradenhilton deleted the mermaid-theme branch August 21, 2023 14:58
@bradenhilton
Copy link
Collaborator Author

Oops. I forgot that renaming a branch automatically closes PRs.

@bradenhilton
Copy link
Collaborator Author

The changes are now on my native-mermaid branch. Again, happy to revisit whenever, no worries! :)

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Feb 10, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

doc: sequence diagram in dark mode
2 participants
@bradenhilton @twpayne