github-com-docker-mailserver/docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2024-01-19 02:48:50 +00:00
Code Issues Projects Releases Wiki Activity
docker-mailserver/docs/mkdocs.yml

135 lines
6.1 KiB
YAML
Raw Normal View History

docs(config): Tidy up and better document `mkdocs.yml`
2021-03-10 04:30:57 +00:00
# Site specific:
docs(config): Add initial `mkdocs.yml` config
2021-02-28 11:53:15 +00:00
site_name: 'Docker Mailserver'
site_description: 'A fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.) using Docker.'
site_author: 'docker-mailserver (Github Organization)'
docs(config): Tidy up and better document `mkdocs.yml`
2021-03-10 04:30:57 +00:00
copyright: '<p>&copy <a href="https://github.com/docker-mailserver"><em>Docker Mailserver Organization</em></a><br/><span>This project is licensed under the MIT license.</span></p>'
# Project source specific:
docs(config): Add initial `mkdocs.yml` config
2021-02-28 11:53:15 +00:00
repo_name: 'docker-mailserver'
repo_url: 'https://github.com/docker-mailserver/docker-mailserver'
docs(config): Tidy up and better document `mkdocs.yml`
2021-03-10 04:30:57 +00:00
# All docs `edit` button will go to this subpath of the `repo_url`:
# For versioned docs, this may be a little misleading for a user not viewing the `edge` docs which match the `master` branch.
docs(config): Add the nav section Various PR commits related to the nav section have been merged together: docs: Fix indentation for linter check docs: update edit uri to content subdirectory docs: add ghcr link docs: shorten nav entry name docs: quote ghcr nav entry docs(config): update nav section for relocated documents Additional nav section fixes: - consistent usage of quotes - eclint padding error - wrong indentation of pop3 - remove a leading slash from a filepath
2021-03-02 17:48:28 +00:00
edit_uri: 'edit/master/docs/content'
docs(config): Tidy up and better document `mkdocs.yml`
2021-03-10 04:30:57 +00:00
# The main docs content lives here, any files will be copied over to the deployed version,
# unless the file or directory name is prefixed with a `.`
docs(config): Add initial `mkdocs.yml` config
2021-02-28 11:53:15 +00:00
docs_dir: 'content/'
docs(config): Tidy up and better document `mkdocs.yml`
2021-03-10 04:30:57 +00:00
# Canonical URL (HTML content instructs search engines that this is where the preferred version of the docs is located, useful when we have duplicate content like versioned docs)
# https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Choosing_between_www_and_non-www_URLs#using_%3Clink_relcanonical%3E
# Also required for `sitemap.xml` generation at build time; which bots use to assist them crawling and indexing a website,
# the `mkdocs-material` 'Instant Navigation' feature utilizes the sitemap data to work.
site_url: 'https://docker-mailserver.github.io/docker-mailserver/edge'
# Anything related to the `mkdocs-material` theme config goes here:
docs(config): Add initial `mkdocs.yml` config
2021-02-28 11:53:15 +00:00
theme:
name: 'material'
docs(assets): Add SVG logo and ICO favicon. Adds the SVG logo I created (composited rather) in mid-feb in one of my PRs that went slightly off-topic about migrating docs from Github Wiki. Enables the logo and favicon in `mkdocs.yml`. SVG sources for both full colour and simplified monochromatic are included along with PNG images for use anywhere else, such as the organization logo. The two SVG of the same names from `src` dir, are used by the docs and have been processed through SVGOMG, an SVG file size optimizer. Any future modifications should use the source files.
2021-03-04 12:39:26 +00:00
favicon: assets/logo/favicon-32x32.png
logo: assets/logo/dmo-logo-white.svg
docs(config): Add initial `mkdocs.yml` config
2021-02-28 11:53:15 +00:00
icon:
repo: fontawesome/brands/github
features:
- navigation.tabs
- navigation.expand
docs(styles): Add external link icon workaround Adds some third-party CSS as`mkdocs-material` doesn't seem interested in a PR to upstream this feature to the community. --- Uses a font icon approach for the external link as alternatives like SVG was reported in PR as breaking on Chrome. The logo has been made larger than theme default, it needs a little push from the left to align well with the tabs below it. --- Unrelated: Additionally experiment with the Instant Navigation feature. --- docs(styles): Various improvements Multiple related commits from original PR have been squashed into this. Some messages may be redundant due to loss of history. --- docs(styles): Minor improvements - Use relative path for external-link - UI enhancement for version selector - Improve inline documentation for `customizations.css` Make separate styling sections more evident (since we're not using multiple files or build tools). --- docs(styles): Replace permalink to fix UX bug --- docs(styles): Replace permalink feature for alternative approach Previous commit already switched `permalink` for `anchorlink` option, but the `#` symbol had UI concerns regarding font-size/scale and fitting into the gutter. Gutter change reverted, switch to REM units and symbol replaced by thin vertical rectangle scaled by font height, far better consistency for placement. --- docs(styles): Refactor the heading link style Effectively ended up making a border-left line style, just not as consistent and more complicated. Fixed that by adjusting styles. Adds optional background fill and restores inline code style for headings.
2021-03-11 03:49:43 +00:00
- navigation.instant
docs(config): Tidy up and better document `mkdocs.yml`
2021-03-10 04:30:57 +00:00
# We make some minor style adjustments or resolve issues that upstream `mkdocs-material` would not accept a PR for:
docs(styles): Add external link icon workaround Adds some third-party CSS as`mkdocs-material` doesn't seem interested in a PR to upstream this feature to the community. --- Uses a font icon approach for the external link as alternatives like SVG was reported in PR as breaking on Chrome. The logo has been made larger than theme default, it needs a little push from the left to align well with the tabs below it. --- Unrelated: Additionally experiment with the Instant Navigation feature. --- docs(styles): Various improvements Multiple related commits from original PR have been squashed into this. Some messages may be redundant due to loss of history. --- docs(styles): Minor improvements - Use relative path for external-link - UI enhancement for version selector - Improve inline documentation for `customizations.css` Make separate styling sections more evident (since we're not using multiple files or build tools). --- docs(styles): Replace permalink to fix UX bug --- docs(styles): Replace permalink feature for alternative approach Previous commit already switched `permalink` for `anchorlink` option, but the `#` symbol had UI concerns regarding font-size/scale and fitting into the gutter. Gutter change reverted, switch to REM units and symbol replaced by thin vertical rectangle scaled by font height, far better consistency for placement. --- docs(styles): Refactor the heading link style Effectively ended up making a border-left line style, just not as consistent and more complicated. Fixed that by adjusting styles. Adds optional background fill and restores inline code style for headings.
2021-03-11 03:49:43 +00:00
extra_css:
- assets/css/customizations.css
docs(config): Add initial `mkdocs.yml` config
2021-02-28 11:53:15 +00:00
docs(ci): Add versioning support without using 'mike' It seems it may have be simpler to just use 'mike'.. Additionally squashes related commits providing minor fixes + improvements: - Use a job dependency (`needs`) to avoid `push` event race conditions due to parallel jobs. - Improve workflow file documentation via inline comments. - Make ShellCheck linting happy. - `chown` doesn't seem to work unless on the default branch for CI. Opted to use the docker `--user` approach instead.
2021-03-11 04:57:16 +00:00
# We do not use `mike`, but enabling this will enable the version selector UI.
# It references `versions.json` on `gh-pages` branch,
# however we have a basic setup that only matches `version` to a subdirectory.
extra:
version:
provider: mike
docs(config): Tidy up and better document `mkdocs.yml`
2021-03-10 04:30:57 +00:00
# Various extensions for `mkdocs` are enabled and configured here to extend supported markdown syntax/features.
docs(config): Add initial `mkdocs.yml` config
2021-02-28 11:53:15 +00:00
markdown_extensions:
- toc:
docs(styles): Add external link icon workaround Adds some third-party CSS as`mkdocs-material` doesn't seem interested in a PR to upstream this feature to the community. --- Uses a font icon approach for the external link as alternatives like SVG was reported in PR as breaking on Chrome. The logo has been made larger than theme default, it needs a little push from the left to align well with the tabs below it. --- Unrelated: Additionally experiment with the Instant Navigation feature. --- docs(styles): Various improvements Multiple related commits from original PR have been squashed into this. Some messages may be redundant due to loss of history. --- docs(styles): Minor improvements - Use relative path for external-link - UI enhancement for version selector - Improve inline documentation for `customizations.css` Make separate styling sections more evident (since we're not using multiple files or build tools). --- docs(styles): Replace permalink to fix UX bug --- docs(styles): Replace permalink feature for alternative approach Previous commit already switched `permalink` for `anchorlink` option, but the `#` symbol had UI concerns regarding font-size/scale and fitting into the gutter. Gutter change reverted, switch to REM units and symbol replaced by thin vertical rectangle scaled by font height, far better consistency for placement. --- docs(styles): Refactor the heading link style Effectively ended up making a border-left line style, just not as consistent and more complicated. Fixed that by adjusting styles. Adds optional background fill and restores inline code style for headings.
2021-03-11 03:49:43 +00:00
anchorlink: true
docs(config): Add initial `mkdocs.yml` config
2021-02-28 11:53:15 +00:00
- abbr
- attr_list
- admonition
docs(refactor): Large refactor + additions + fixes Consistency pass, formatting cleanup and fixes, introduce admonitions, add front-matter. --- docs: Add front-matter --- docs: Fix and format links - Some links were invalid (eg files moved or renamed) - Some were valid but had invalid section headers (content removed or migrated) - Some use `http://` instead of `https://` when the website supports a secure connection. - Some already used the `[name][reference]` convention but often with a number that wasn't as useful for maintenance. - All referenced docs needed URLs replaced. Opted for the `[name][reference]` approach to group them all clearly at the bottom of the doc, especially with the relative URLs and in some cases many duplicate entries. - All `tomav` references from the original repo prior to switch to an organization have been corrected. - Minor cosmetic changes to the `name` part of the URL, such as for referencing issues to be consistent. - Some small changes to text body, usually due to duplicate URL reference that was unnecessary (open relay, youtous) - Switched other links to use the `[name][reference]` format when there was a large group of URLs such as wikipedia or kubernetes. Github repos that reference projects related to `docker-mailserver` also got placed here so they're noticed better by maintainers. This also helped quite a bit with `mermaid` external links that are very long. - There was a Github Wiki supported syntax in use `[[name | link]]` for `fetchmail` page that isn't compatible by default with MkDocs (needs a plugin), converted to `[name][reference]` instead since it's a relative link. --- docs: Update commit link for LDAP override script Logic moved to another file, keeping the permalink commit reference so it's unaffected by any changes in the file referenced in future. --- docs: Heading corrections Consistency pass. Helps with the Table of Contents (top-right UI) aka Document Outline. docs: codefence cleanup --- docs: misc cleanup --- docs: Add Admonitions Switches `<details>` usage for collapsible admonitions (`???`) while other text content is switched to the visually more distinct admoniton (`!!!` or `???+`) style. This does affect editor syntax highlighting a bit and markdown linting as it's custom non-standard markdown syntax.
2021-03-01 10:41:19 +00:00
- pymdownx.details
docs(config): Tidy up and better document `mkdocs.yml`
2021-03-10 04:30:57 +00:00
- pymdownx.superfences
- pymdownx.magiclink
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
docs(config): Add initial `mkdocs.yml` config
2021-02-28 11:53:15 +00:00
- pymdownx.highlight:
extend_pygments_lang:
- name: yml
lang: yaml
- name: cf
lang: cfg
- name: conf
lang: cfg
docs(refactor): Large refactor + additions + fixes Consistency pass, formatting cleanup and fixes, introduce admonitions, add front-matter. --- docs: Add front-matter --- docs: Fix and format links - Some links were invalid (eg files moved or renamed) - Some were valid but had invalid section headers (content removed or migrated) - Some use `http://` instead of `https://` when the website supports a secure connection. - Some already used the `[name][reference]` convention but often with a number that wasn't as useful for maintenance. - All referenced docs needed URLs replaced. Opted for the `[name][reference]` approach to group them all clearly at the bottom of the doc, especially with the relative URLs and in some cases many duplicate entries. - All `tomav` references from the original repo prior to switch to an organization have been corrected. - Minor cosmetic changes to the `name` part of the URL, such as for referencing issues to be consistent. - Some small changes to text body, usually due to duplicate URL reference that was unnecessary (open relay, youtous) - Switched other links to use the `[name][reference]` format when there was a large group of URLs such as wikipedia or kubernetes. Github repos that reference projects related to `docker-mailserver` also got placed here so they're noticed better by maintainers. This also helped quite a bit with `mermaid` external links that are very long. - There was a Github Wiki supported syntax in use `[[name | link]]` for `fetchmail` page that isn't compatible by default with MkDocs (needs a plugin), converted to `[name][reference]` instead since it's a relative link. --- docs: Update commit link for LDAP override script Logic moved to another file, keeping the permalink commit reference so it's unaffected by any changes in the file referenced in future. --- docs: Heading corrections Consistency pass. Helps with the Table of Contents (top-right UI) aka Document Outline. docs: codefence cleanup --- docs: misc cleanup --- docs: Add Admonitions Switches `<details>` usage for collapsible admonitions (`???`) while other text content is switched to the visually more distinct admoniton (`!!!` or `???+`) style. This does affect editor syntax highlighting a bit and markdown linting as it's custom non-standard markdown syntax.
2021-03-01 10:41:19 +00:00
- name: env
lang: properties
# Not helpful with Python Pygments lexer highlighting, but we might change to a JS highlighter in future
# Ideally, this type of codefence might also have word-wrap enabled (CSS: {white-space: pre-wrap})
- name: log
lang: shell-session
- name: fetchmailrc
lang: txt
- name: caddyfile
lang: txt
docs(config): Add the nav section Various PR commits related to the nav section have been merged together: docs: Fix indentation for linter check docs: update edit uri to content subdirectory docs: add ghcr link docs: shorten nav entry name docs: quote ghcr nav entry docs(config): update nav section for relocated documents Additional nav section fixes: - consistent usage of quotes - eclint padding error - wrong indentation of pop3 - remove a leading slash from a filepath
2021-03-02 17:48:28 +00:00
docs(config): Tidy up and better document `mkdocs.yml`
2021-03-10 04:30:57 +00:00
# Hard-coded navigation list. Key(UI label): Value(relative filepath from `docs_dir`).
# - If referencing a file more than once, the URLs will all point to the nav hierarchy of the last file reference entry. That usually breaks UX, try avoid it.
# - The top-level elements are presented as tabs (due to `theme.features.navigation.tabs`).
# - Nested elements appear in the sidebar (left) of each tabs page.
# - 3rd level and beyond are automatically expanded in the sidebar instead of collapsed (due to `theme.features.navigation.expand`)
docs(config): Add the nav section Various PR commits related to the nav section have been merged together: docs: Fix indentation for linter check docs: update edit uri to content subdirectory docs: add ghcr link docs: shorten nav entry name docs: quote ghcr nav entry docs(config): update nav section for relocated documents Additional nav section fixes: - consistent usage of quotes - eclint padding error - wrong indentation of pop3 - remove a leading slash from a filepath
2021-03-02 17:48:28 +00:00
nav:
- 'Home': index.md
- 'Introduction': introduction.md
- 'Configuration':
- 'Your Best Friend setup.sh': config/setup.sh.md
- 'User Management':
- 'Accounts': config/user-management/accounts.md
- 'Aliases': config/user-management/aliases.md
- 'Best Practices':
- 'DKIM': config/best-practices/dkim.md
- 'DMARC': config/best-practices/dmarc.md
- 'SPF': config/best-practices/spf.md
- 'Auto-discovery': config/best-practices/autodiscover.md
- 'Security':
- 'Understanding the Ports': config/security/understanding-the-ports.md
- 'SSL/TLS': config/security/ssl.md
- 'Fail2Ban': config/security/fail2ban.md
- 'Troubleshooting':
- 'Debugging': config/troubleshooting/debugging.md
- 'Mail Delivery with POP3': config/pop3.md
- 'Advanced Configuration':
- 'Optional Configuration': config/advanced/optional-config.md
- 'Maintenance':
- 'Update and Cleanup': config/advanced/maintenance/update-and-cleanup.md
- 'Override the Default Configs':
- 'Dovecot': config/advanced/override-defaults/dovecot.md
- 'Postfix': config/advanced/override-defaults/postfix.md
- 'LDAP Authentication': config/advanced/auth-ldap.md
- 'Email Filtering with Sieve': config/advanced/mail-sieve.md
- 'Email Gathering with Fetchmail': config/advanced/mail-fetchmail.md
- 'Email Forwarding':
- 'Relay Hosts': config/advanced/mail-forwarding/relay-hosts.md
- 'AWS SES': config/advanced/mail-forwarding/aws-ses.md
- 'Full-Text Search': config/advanced/full-text-search.md
- 'Kubernetes': config/advanced/kubernetes.md
- 'IPv6': config/advanced/ipv6.md
- 'Examples':
- 'Tutorials':
- 'Basic Installation': examples/tutorials/basic-installation.md
- 'Mailserver behind Proxy': examples/tutorials/mailserver-behind-proxy.md
- 'Use Cases':
- 'Forward-Only Mailserver with LDAP': examples/uses-cases/forward-only-mailserver-with-ldap-authentication.md
docs: Update metadata and links to new locations Also removed the FAQ inline heading link for Rancher. It's not a relevant link (as the question already expects knowledge of Rancher), and breaks out of the bg colour heading style due to the HTML generation logic from mkdocs.
2021-03-11 19:41:24 +00:00
- 'FAQ' : faq.md
docs(config): Add the nav section Various PR commits related to the nav section have been merged together: docs: Fix indentation for linter check docs: update edit uri to content subdirectory docs: add ghcr link docs: shorten nav entry name docs: quote ghcr nav entry docs(config): update nav section for relocated documents Additional nav section fixes: - consistent usage of quotes - eclint padding error - wrong indentation of pop3 - remove a leading slash from a filepath
2021-03-02 17:48:28 +00:00
- 'Contributing':
- 'Issues and Pull Requests': contributing/issues-and-pull-requests.md
- 'Coding Style': contributing/coding-style.md
- 'Tests': contributing/tests.md
- 'Documentation': contributing/documentation.md
- 'DockerHub': https://hub.docker.com/repository/docker/mailserver/docker-mailserver
- 'GHCR': https://github.com/orgs/docker-mailserver/packages/container/package/docker-mailserver
Reference in a new issue Copy permalink