Add AI documentation skills

2026-04-25 09:08:55 -05:00
parent 100a4d5419
commit 9d15ab56c6
255 changed files with 68574 additions and 0 deletions
--- a/.ai/skills/mkdocs/references/upstream/mkdocs-material-9.7.1-docs/publishing-your-site.md
+++ b/.ai/skills/mkdocs/references/upstream/mkdocs-material-9.7.1-docs/publishing-your-site.md
@@ -0,0 +1,193 @@
+# Publishing your site
+
+The great thing about hosting project documentation in a `git` repository is
+the ability to deploy it automatically when new changes are pushed. MkDocs
+makes this ridiculously simple.
+
+## GitHub Pages
+
+If you're already hosting your code on GitHub, [GitHub Pages] is certainly
+the most convenient way to publish your project documentation. It's free of
+charge and pretty easy to set up.
+
+  [GitHub Pages]: https://pages.github.com/
+
+### with GitHub Actions
+
+Using [GitHub Actions] you can automate the deployment of your project
+documentation. At the root of your repository, create a new GitHub Actions
+workflow, e.g. `.github/workflows/ci.yml`, and copy and paste the following
+contents:
+
+``` yaml
+name: ci # (1)!
+on:
+  push:
+    branches:
+      - master # (2)!
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache # (4)!
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material # (5)!
+      - run: mkdocs gh-deploy --force
+```
+
+1.  You can change the name to your liking.
+
+2.  At some point, GitHub renamed `master` to `main`. If your default branch
+    is named `master`, you can safely remove `main`, vice versa.
+
+3.  Store the `cache_id` environmental variable to access it later during cache
+    `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`.
+
+    - The `--utc` option makes sure that each workflow runner uses the same time zone.
+    - The `%V` format assures a cache update once a week.
+    - You can change the format to `%F` to have daily cache updates.
+
+    You can read the [manual page] to learn more about the formatting options of the `date` command.
+
+4.  Some Material for MkDocs plugins use [caching] to speed up repeated
+    builds, and store the results in the `~/.cache` directory.
+
+5.  This is the place to install further [MkDocs plugins] or Markdown
+    extensions with `pip` to be used during the build:
+
+    ``` sh
+    pip install \
+      mkdocs-material \
+      mkdocs-awesome-pages-plugin \
+      ...
+    ```
+
+Now, when a new commit is pushed to either the `master` or `main` branches,
+the static site is automatically built and deployed. Push your changes to see
+the workflow in action.
+
+If the GitHub Page doesn't show up after a few minutes, go to the settings of
+your repository and ensure that the [publishing source branch] for your GitHub
+Page is set to `gh-pages`.
+
+Your documentation should shortly appear at `<username>.github.io/<repository>`.
+
+To publish your site on a custom domain, please refer to the [MkDocs documentation].
+
+  [GitHub Actions]: https://github.com/features/actions
+  [MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
+  [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+  [built-in optimize plugin]: plugins/optimize.md
+  [GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
+  [publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
+  [manual page]: https://man7.org/linux/man-pages/man1/date.1.html
+  [caching]: plugins/requirements/caching.md
+  [MkDocs documentation]: https://www.mkdocs.org/user-guide/deploying-your-docs/#custom-domains
+
+### with MkDocs
+
+If you prefer to deploy your project documentation manually, you can just invoke
+the following command from the directory containing the `mkdocs.yml` file:
+
+```
+mkdocs gh-deploy --force
+```
+
+This will build your documentation and deploy it to a branch
+`gh-pages` in your repository. See [this overview in the MkDocs
+documentation] for more information. For a description of the
+arguments, see [the documentation for the command].
+
+  [this overview in the MkDocs documentation]: https://www.mkdocs.org/user-guide/deploying-your-docs/#project-pages
+  [the documentation for the command]: https://www.mkdocs.org/user-guide/cli/#mkdocs-gh-deploy
+
+## GitLab Pages
+
+If you're hosting your code on GitLab, deploying to [GitLab Pages] can be done
+by using the [GitLab CI] task runner. At the root of your repository, create a
+task definition named `.gitlab-ci.yml` and copy and paste the following
+contents:
+
+``` yaml
+pages:
+  stage: deploy
+  image: python:latest
+  script:
+    - pip install mkdocs-material
+    - mkdocs build --site-dir public
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - ~/.cache/ # (1)!
+  artifacts:
+    paths:
+      - public
+  rules:
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+```
+
+1.  Some Material for MkDocs plugins use [caching] to speed up repeated
+    builds, and store the results in the `~/.cache` directory.
+
+Now, when a new commit is pushed to the [default branch] (typically `master` or
+`main`), the static site is automatically built and deployed. Commit and push
+the file to your repository to see the workflow in action.
+
+Your documentation is not published under `<username>.gitlab.io/<repository>`
+by default since **GitLab 17.4** [^1]. However, if you prefer a cleaner URL
+structure, such as `<username>.gitlab.io/<repository>`, you need to adjust
+your configuration.
+
+To switch from a unique domain to the traditional URL structure, follow
+these steps:
+
+1.  Locate Your Repository
+2.  Go to **Settings › Pages** in the repository menu.
+3.  In the **Unique domain settings** section, **uncheck** the box labeled
+4.  **Use unique domain**.
+5.  Click **Save changes** to apply the update.
+
+Now you can reach your documentation under `<username>.gitlab.io/<repository>`.
+
+[^1]: [Release notes for Gitlab 17.4](https://about.gitlab.com/releases/2024/09/19/gitlab-17-4-released/)
+
+## Other
+
+Since we can't cover all possible platforms, we rely on community contributed
+guides that explain how to deploy websites built with Material for MkDocs to
+other providers:
+
+<div class="mdx-columns" markdown>
+
+- [:simple-cloudflarepages: Cloudflare Pages][Cloudflare Pages]
+- [:material-airballoon-outline: Fly.io][Flyio]
+- [:simple-netlify: Netlify][Netlify]
+- [:simple-scaleway: Scaleway][Scaleway]
+
+</div>
+
+  [GitLab Pages]: https://gitlab.com/pages
+  [GitLab CI]: https://docs.gitlab.com/ee/ci/
+  [masked custom variables]: https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable
+  [default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html
+  [Cloudflare Pages]: https://deborahwrites.com/guides/deploy-host-mkdocs/deploy-mkdocs-material-cloudflare/
+  [Flyio]: https://documentation.breadnet.co.uk/cloud/fly/mkdocs-on-fly/
+  [Netlify]: https://deborahwrites.com/guides/deploy-host-mkdocs/deploy-mkdocs-material-netlify/
+  [Scaleway]: https://www.scaleway.com/en/docs/tutorials/using-bucket-website-with-mkdocs/
+