diff --git a/.github/workflows/docs-preview-deploy.yml b/.github/workflows/docs-preview-deploy.yml new file mode 100644 index 00000000..c1c63118 --- /dev/null +++ b/.github/workflows/docs-preview-deploy.yml @@ -0,0 +1,119 @@ +name: 'Documentation (run)' + +on: + workflow_run: + workflows: ['Documentation (PR)'] + types: + - completed + +# Note: If limiting concurrency is required for this workflow: +# 1. Add an additional job prior to `preview` to get the PR number make it an output. +# 2. Assign that new job as a `needs` dependency for the `preview` job. +# It is still required for `preview` job to download the artifact so that it can access the preview build files. + +# This workflow runs off the primary branch and has access to secrets as expected. +jobs: + preview: + name: 'Deploy Preview' + runs-on: ubuntu-20.04 + if: ${{ github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' }} + steps: + + # ======================== # + # Restore workflow context # + # ======================== # + + # The official Github Action for downloading artifacts does not support multi-workflow + - name: 'Download build artifact' + uses: dawidd6/action-download-artifact@v2 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + run_id: ${{ github.event.workflow_run.id }} + workflow: docs-preview-prepare.yml + name: preview-build + + - name: 'Extract build artifact' + run: tar -xf artifact.tar.zst + + - name: 'Restore preserved ENV' + run: cat pr.env >> "${GITHUB_ENV}" + + # ==================== # + # Deploy preview build # + # ==================== # + + # Manage workflow deployment status. `enable-commit-status` from `nwtgck/actions-netlify` would handle this, + # but presently does not work correctly via split workflow. It is useful in a split workflow as the 1st stage + # no longer indicates if the entire workflow/deployment was successful. + - name: 'Commit Status: Set Workflow Status as Pending' + uses: myrotvorets/set-commit-status-action@1.0.2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + status: pending + # Should match `env.PR_HEADSHA` when triggered by `pull_request` event workflow, + # Avoids failure of ENV being unavailable if job fails early: + sha: ${{ github.event.workflow_run.head_sha }} + context: 'Deploy Preview (pull_request => workflow_run)' + + - name: 'Send preview build to Netlify' + uses: nwtgck/actions-netlify@v1.2 + id: preview + timeout-minutes: 1 + env: + NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} + NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + # Fail the job early if credentials are missing / invalid: + fails-without-credentials: true + # Sets/creates the Netlify deploy URL prefix. + # Uses the PR number for uniqueness: + alias: ${{ env.NETLIFY_SITE_PREFIX }} + # Only publish the contents of the build output: + publish-dir: ${{ env.BUILD_DIR }} + # Custom message for the deploy log on Netlify: + deploy-message: '${{ env.PR_TITLE }} (PR #${{ env.PR_NUMBER }} @ commit: ${{ env.PR_HEADSHA }})' + + # Note: Split workflow incorrectly references latest primary branch commit for deployment. + # Assign to non-default Deployment Environment for better management: + github-deployment-environment: documentation-previews + github-deployment-description: 'Preview deploy for documentation PRs' + + # Note - PR context used by this action is incorrect. These features are broken with split workflow: + # https://github.com/nwtgck/actions-netlify/issues/545 + # Disable unwanted action defaults: + # Disable adding deploy comment on pre-merge commit (Github creates this for PR diff): + enable-commit-comment: false + # Disable adding a "Netlify - Netlify deployment" check status: + enable-commit-status: false + # Disable. We provide a custom PR comment in the next action: + enable-pull-request-comment: false + + # If a `netlify.toml` config is ever needed, enable this: + # netlify-config-path: ./docs/netlify.toml + # If ever switching from Github Pages, enable this conditionally (false by default): + # production-deploy: false + + - name: 'Comment on PR: Add/Update deployment status' + uses: marocchino/sticky-pull-request-comment@v2 + with: + number: ${{ env.PR_NUMBER }} + header: preview-comment + message: | + [Documentation preview for this PR](${{ steps.preview.outputs.deploy-url }}) is ready! :tada: + + Built with commit: ${{ env.PR_HEADSHA }} + + - name: 'Commit Status: Update deployment status' + uses: myrotvorets/set-commit-status-action@1.0.2 + # Always run this step regardless of job failing early: + if: ${{ always() }} + env: + DEPLOY_SUCCESS: Successfully deployed preview. + DEPLOY_FAILURE: Failed to deploy preview. + with: + token: ${{ secrets.GITHUB_TOKEN }} + status: ${{ job.status == 'success' && 'success' || 'failure' }} + sha: ${{ github.event.workflow_run.head_sha }} + context: 'Deploy Preview (pull_request => workflow_run)' + description: ${{ job.status == 'success' && env.DEPLOY_SUCCESS || env.DEPLOY_FAILURE }} diff --git a/.github/workflows/docs-preview-prepare.yml b/.github/workflows/docs-preview-prepare.yml new file mode 100644 index 00000000..7563eecd --- /dev/null +++ b/.github/workflows/docs-preview-prepare.yml @@ -0,0 +1,70 @@ +name: 'Documentation (PR)' + +on: + pull_request: + paths: + - 'docs/**' + +# If the workflow for a PR is triggered multiple times, previous existing runs will be canceled. +# eg: Applying multiple suggestions from a review directly via the Github UI. +# Instances of the 2nd phase of this workflow (via `workflow_run`) presently lack concurrency limits due to added complexity. +concurrency: + group: deploypreview-pullrequest-${{ github.event.pull_request.number }} + cancel-in-progress: true + +# `pull_request` workflow is unreliable alone: Non-collaborator contributions lack access to secrets for security reasons. +# A separate workflow (docs-preview-deploy.yml) handles the deploy after the potentially untrusted code is first run in this workflow. +# See: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/ +jobs: + prepare-preview: + name: 'Build Preview' + runs-on: ubuntu-20.04 + env: + BUILD_DIR: docs/site + NETLIFY_SITE_PREFIX: pullrequest-${{ github.event.pull_request.number }} + NETLIFY_SITE_NAME: dms-doc-previews + steps: + - uses: actions/checkout@v2.3.4 + + - name: 'Build with mkdocs-material via Docker' + working-directory: docs + env: + PREVIEW_URL: 'https://${NETLIFY_SITE_PREFIX}--${NETLIFY_SITE_NAME}.netlify.app/' + NETLIFY_BRANDING: 'Deploys by Netlify' + run: | + # Adjust mkdocs.yml for preview build + sed -i "s|^site_url:.*|site_url: '${PREVIEW_URL}'|" mkdocs.yml + + # Insert sponsor branding into page content (Provider OSS plan requirement): + # Upstream does not provide a nicer maintainable way to do this.. + # Prepends HTML to copyright text and then aligns to the right side. + sed -i "s|^copyright: '|copyright: '${NETLIFY_BRANDING}|" mkdocs.yml + # Need to override a CSS media query for parent element to always be full width: + echo '.md-footer-copyright { width: 100%; }' >> content/assets/css/customizations.css + + ../.github/workflows/scripts/docs/build-docs.sh + + # ============================== # + # Volley over to secure workflow # + # ============================== # + + # Minimize risk of upload failure by bundling files to a single compressed archive (tar + zstd). + # Bundles build dir and env file into a compressed archive, nested file paths will be preserved. + - name: 'Prepare artifact for transfer' + run: | + # Save ENV for transfer + echo "PR_HEADSHA=${{ github.event.pull_request.head.sha }}" >> pr.env + echo "PR_NUMBER=${{ github.event.pull_request.number }}" >> pr.env + echo "PR_TITLE=${{ github.event.pull_request.title }}" >> pr.env + echo "NETLIFY_SITE_PREFIX=${{ env.NETLIFY_SITE_PREFIX }}" >> pr.env + echo "BUILD_DIR=${{ env.BUILD_DIR }}" >> pr.env + + tar --zstd -cf artifact.tar.zst pr.env ${{ env.BUILD_DIR }} + + - name: 'Upload artifact for workflow transfer' + uses: actions/upload-artifact@v2 + with: + name: preview-build + path: artifact.tar.zst + retention-days: 1 + diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/docs-production-deploy.yml similarity index 90% rename from .github/workflows/deploy-docs.yml rename to .github/workflows/docs-production-deploy.yml index a9137fb8..539e4526 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/docs-production-deploy.yml @@ -40,8 +40,7 @@ jobs: - name: 'Build with mkdocs-material via Docker' working-directory: docs - # --user is required for build output file ownership to match the CI user instead of the containers internal user - run: docker run --rm --user "$(id -u):$(id -g)" -v "${PWD}:/docs" squidfunk/mkdocs-material:7.1.4 build --strict + run: '../.github/workflows/scripts/docs/build-docs.sh' - name: 'If a tagged version, fix canonical links and remove `404.html`' if: startsWith(github.ref, 'refs/tags/') @@ -51,8 +50,8 @@ jobs: # (Note the edge 404.html isn't useful either as it's not copied to the `gh-pages` branch root) rm 404.html - # Replace '${DOCS_VERSION}' (defaults to 'edge') in the 'canonical' link element of HTML files, - # with the tagged docs version: + # Replace the tagged '${DOCS_VERSION}' in the 'canonical' link element of HTML files, + # to point to the 'edge' version of docs as the authoritative source: find . -type f -name "*.html" -exec \ sed -i "s|^\(.*` version and any suffix beyond it. local MAJOR_MINOR MAJOR_MINOR=$(grep -oE 'v[0-9]+\.[0-9]+' <<< "${GITHUB_REF}") diff --git a/docs/content/assets/logo/.src/dmo-logo-white.png b/docs/content/assets/logo/.src/dmo-logo-white.png new file mode 100644 index 00000000..8bc42012 Binary files /dev/null and b/docs/content/assets/logo/.src/dmo-logo-white.png differ diff --git a/docs/content/assets/logo/.src/dmo-logo-white.svg b/docs/content/assets/logo/.src/dmo-logo-white.svg new file mode 100644 index 00000000..63c01254 --- /dev/null +++ b/docs/content/assets/logo/.src/dmo-logo-white.svg @@ -0,0 +1,30 @@ + + + + + + + + + diff --git a/docs/content/assets/logo/.src/dmo-logo.png b/docs/content/assets/logo/.src/dmo-logo.png new file mode 100644 index 00000000..47cde8da Binary files /dev/null and b/docs/content/assets/logo/.src/dmo-logo.png differ diff --git a/docs/content/assets/logo/.src/dmo-logo.svg b/docs/content/assets/logo/.src/dmo-logo.svg new file mode 100644 index 00000000..9d95ec14 --- /dev/null +++ b/docs/content/assets/logo/.src/dmo-logo.svg @@ -0,0 +1,55 @@ + + diff --git a/docs/content/assets/logo/dmo-logo-white.min.svg b/docs/content/assets/logo/dmo-logo-white.min.svg new file mode 100644 index 00000000..7ec0dbb3 --- /dev/null +++ b/docs/content/assets/logo/dmo-logo-white.min.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/content/assets/logo/dmo-logo-white.svg b/docs/content/assets/logo/dmo-logo-white.svg deleted file mode 100644 index 70d4bfac..00000000 --- a/docs/content/assets/logo/dmo-logo-white.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/content/assets/logo/dmo-logo.min.svg b/docs/content/assets/logo/dmo-logo.min.svg new file mode 100644 index 00000000..72c98a5a --- /dev/null +++ b/docs/content/assets/logo/dmo-logo.min.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/content/assets/logo/dmo-logo.svg b/docs/content/assets/logo/dmo-logo.svg deleted file mode 100644 index d738edb3..00000000 --- a/docs/content/assets/logo/dmo-logo.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/content/assets/logo/src/dmo-logo-white.png b/docs/content/assets/logo/src/dmo-logo-white.png deleted file mode 100644 index 57683598..00000000 Binary files a/docs/content/assets/logo/src/dmo-logo-white.png and /dev/null differ diff --git a/docs/content/assets/logo/src/dmo-logo-white.svg b/docs/content/assets/logo/src/dmo-logo-white.svg deleted file mode 100644 index da1f78b9..00000000 --- a/docs/content/assets/logo/src/dmo-logo-white.svg +++ /dev/null @@ -1,109 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/content/assets/logo/src/dmo-logo.png b/docs/content/assets/logo/src/dmo-logo.png deleted file mode 100644 index cd049f8d..00000000 Binary files a/docs/content/assets/logo/src/dmo-logo.png and /dev/null differ diff --git a/docs/content/assets/logo/src/dmo-logo.svg b/docs/content/assets/logo/src/dmo-logo.svg deleted file mode 100644 index a5979bdf..00000000 --- a/docs/content/assets/logo/src/dmo-logo.svg +++ /dev/null @@ -1,126 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 1dd41957..e21aa799 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -20,13 +20,14 @@ docs_dir: 'content/' # 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' +site_url: 'https://docker-mailserver.github.io/docker-mailserver/edge/' # Anything related to the `mkdocs-material` theme config goes here: theme: name: 'material' + custom_dir: 'overrides/' favicon: assets/logo/favicon-32x32.png - logo: assets/logo/dmo-logo-white.svg + logo: assets/logo/dmo-logo-white.min.svg icon: repo: fontawesome/brands/github features: @@ -36,7 +37,7 @@ theme: - navigation.instant palette: # Light mode - - media: "(prefers-color-scheme: light)" + - media: '(prefers-color-scheme: light)' scheme: default primary: indigo accent: indigo @@ -44,7 +45,7 @@ theme: icon: material/weather-night name: Switch to dark mode # Dark mode - - media: "(prefers-color-scheme: dark)" + - media: '(prefers-color-scheme: dark)' scheme: slate primary: indigo accent: blue diff --git a/docs/overrides/404.html b/docs/overrides/404.html new file mode 100644 index 00000000..f6206dbc --- /dev/null +++ b/docs/overrides/404.html @@ -0,0 +1 @@ +404 - Page not found

4

4

Ahoy there matey! This page be lost at sea..

We found these helpful treasures!

View the Documentation docker-mailserver on Github
diff --git a/docs/overrides/assets/img/bg-water.webp b/docs/overrides/assets/img/bg-water.webp new file mode 100644 index 00000000..5eb84897 Binary files /dev/null and b/docs/overrides/assets/img/bg-water.webp differ diff --git a/docs/overrides/favicon.ico b/docs/overrides/favicon.ico new file mode 100644 index 00000000..7badbc70 Binary files /dev/null and b/docs/overrides/favicon.ico differ