asc/cmba-bylaws
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Add AI documentation skills

Browse Source
This commit is contained in:
Anthony Correa
2026-04-25 09:08:55 -05:00
parent 100a4d5419
commit 9d15ab56c6
255 changed files with 68574 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
.ai/skills/mkdocs/references/upstream/mkdocs-1.6.1-docs/user-guide/README.md Normal file
View File

@@ -0,0 +1,21 @@
# User Guide
Building Documentation with MkDocs
---
The MkDocs User Guide provides documentation for users of MkDocs. See
[Getting Started] for an introductory tutorial. You can jump directly to a
page listed below, or use the *next* and *previous* buttons in the navigation
bar at the top of the page to move through the documentation in order.
- [Installation](installation.md)
- [Writing Your Docs](writing-your-docs.md)
- [Choosing Your Theme](choosing-your-theme.md)
- [Customizing Your Theme](customizing-your-theme.md)
- [Localizing Your Theme](localizing-your-theme.md)
- [Configuration](configuration.md)
- [Command Line Interface](cli.md)
- [Deploying Your Docs](deploying-your-docs.md)
[Getting Started]: ../getting-started.md

229
.ai/skills/mkdocs/references/upstream/mkdocs-1.6.1-docs/user-guide/choosing-your-theme.md Normal file
View File

@@ -0,0 +1,229 @@
# Choosing your Theme
Selecting and configuring a theme.
---
MkDocs includes two built-in themes ([mkdocs](#mkdocs) and
[readthedocs](#readthedocs)), as documented below. However, many [third party
themes] are available to choose from as well.
To choose a theme, set the [theme] configuration option in your `mkdocs.yml`
config file.
```yaml
theme:
name: readthedocs
```
## mkdocs
The default theme, which was built as a custom [Bootstrap] theme, supports almost
every feature of MkDocs.
<div id="mkdocs-theme-images" class="carousel slide carousel-fade" data-bs-ride="carousel">
<div class="carousel-inner">
<div class="carousel-item active">
<img src="../../img/mkdocs_theme_light_mode.png" class="d-block w-100" alt="MkDocs theme in light mode">
</div>
<div class="carousel-item">
<img src="../../img/mkdocs_theme_dark_mode.png" class="d-block w-100" alt="MkDocs theme in dark mode">
</div>
</div>
</div>
In addition to the default [theme configuration options][theme], the `mkdocs` theme
supports the following options:
* **`color_mode`**: Set the default color mode for the theme to one of `light`,
`dark`, or `auto`. The `auto` mode will switch to `light` or `dark` based on
the system configuration of the user's device. Default: `light`.
* **`user_color_mode_toggle`**: Enable a toggle menu in the navigation bar
which allows users to select their preferred `color_mode` (light, dark, auto)
from within the browser and save their preference for future page loads. The
default selection of the toggle menu on first page load is the value set to
`color_mode`. Default: `false`.
![color mode toggle menu](../img/color_mode_toggle_menu.png)
* **`nav_style`**: Adjust the visual style of the top navigation bar. Set to
one of `primary`, `dark` or `light`. Default: `primary`. This option is
independent of the `color_mode` option and must be defined separately.
* **`highlightjs`**: Enables highlighting of source code in code blocks using
the [highlight.js] JavaScript library. Default: `True`.
* **`hljs_style`**: The highlight.js library provides many different [styles]
(color variations) for highlighting source code in code blocks. Set this to
the name of the desired style when in `light` mode. Default: `github`.
* **`hljs_style_dark`**: Set this to the name of the desired highlight.js
style when in `dark` mode. Default: `github_dark`.
* **`hljs_languages`**: By default, highlight.js only supports 23 common
languages. List additional languages here to include support for them.
```yaml
theme:
name: mkdocs
highlightjs: true
hljs_languages:
- yaml
- rust
```
* **`analytics`**: Defines configuration options for an analytics service.
Currently, only Google Analytics v4 is supported via the `gtag` option.
* **`gtag`**: To enable Google Analytics, set to a Google Analytics v4
tracking ID, which uses the `G-` format. See Google's documentation to
[Set up Analytics for a website and/or app (GA4)][setup-GA4] or to
[Upgrade to a Google Analytics 4 property][upgrade-GA4].
```yaml
theme:
name: mkdocs
analytics:
gtag: G-ABC123
```
When set to the default (`null`) Google Analytics is disabled for the
site.
* **`shortcuts`**: Defines keyboard shortcut keys.
```yaml
theme:
name: mkdocs
shortcuts:
help: 191 # ?
next: 78 # n
previous: 80 # p
search: 83 # s
```
All values must be numeric key codes. It is best to use keys that are
available on all keyboards. You may use <https://keycode.info/> to determine
the key code for a given key.
* **`help`**: Display a help modal that lists the keyboard shortcuts.
Default: `191` (&quest;)
* **`next`**: Navigate to the "next" page. Default: `78` (n)
* **`previous`**: Navigate to the "previous" page. Default: `80` (p)
* **`search`**: Display the search modal. Default: `83` (s)
* **`navigation_depth`**: The maximum depth of the navigation tree in the
sidebar. Default: `2`.
* **`locale`**{ #mkdocs-locale }: The locale (language/location) used to
build the theme. If your locale is not yet supported, it will fall back
to the default.
The following locales are supported by this theme:
* `en`: English (default)
* (see the list of existing directories `mkdocs/themes/mkdocs/locales/*/`)
See the guide on [localizing your theme] for more information.
## readthedocs
A clone of the default theme used by the [Read the Docs] service, which offers
the same restricted feature set as its parent theme. Like its parent theme, only
two levels of navigation are supported.
![ReadTheDocs](../img/readthedocs.png)
In addition to the default [theme configuration options][theme], the `readthedocs`
theme supports the following options:
* **`highlightjs`**: Enables highlighting of source code in code blocks using
the [highlight.js] JavaScript library. Default: `True`.
* **`hljs_languages`**: By default, highlight.js only supports 23 common
languages. List additional languages here to include support for them.
```yaml
theme:
name: readthedocs
highlightjs: true
hljs_languages:
- yaml
- rust
```
* **`analytics`**: Defines configuration options for an analytics service.
* **`gtag`**: To enable Google Analytics, set to a Google Analytics v4
tracking ID, which uses the `G-` format. See Google's documentation to
[Set up Analytics for a website and/or app (GA4)][setup-GA4] or to
[Upgrade to a Google Analytics 4 property][upgrade-GA4].
```yaml
theme:
name: readthedocs
analytics:
gtag: G-ABC123
```
When set to the default (`null`) Google Analytics is disabled for the
* **`anonymize_ip`**: To enable anonymous IP address for Google Analytics,
set this to `True`. Default: `False`.
* **`include_homepage_in_sidebar`**: Lists the homepage in the sidebar menu. As
MkDocs requires that the homepage be listed in the `nav` configuration
option, this setting allows the homepage to be included or excluded from
the sidebar. Note that the site name/logo always links to the homepage.
Default: `True`.
* **`prev_next_buttons_location`**: One of `bottom`, `top`, `both` , or `none`.
Displays the “Next” and “Previous” buttons accordingly. Default: `bottom`.
* **`navigation_depth`**: The maximum depth of the navigation tree in the
sidebar. Default: `4`.
* **`collapse_navigation`**: Only include the page section headers in the
sidebar for the current page. Default: `True`.
* **`titles_only`**: Only include page titles in the sidebar, excluding all
section headers for all pages. Default: `False`.
* **`sticky_navigation`**: If True, causes the sidebar to scroll with the main
page content as you scroll the page. Default: `True`.
* **`locale`**{ #readthedocs-locale }: The locale (language/location) used to
build the theme. If your locale is not yet supported, it will fall back
to the default.
The following locales are supported by this theme:
* `en`: English (default)
* (see the list of existing directories `mkdocs/themes/readthedocs/locales/*/`)
See the guide on [localizing your theme] for more information.
* **`logo`**: To set a logo on your project instead of the plain text
`site_name`, set this variable to be the location of your image. Default: `null`.
## Third Party Themes
A list of third party themes can be found at the [community wiki] page and [the ranked catalog][catalog]. If you have created your own, please add them there.
WARNING: Installing an MkDocs theme means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing.
[third party themes]: #third-party-themes
[theme]: configuration.md#theme
[Bootstrap]: https://getbootstrap.com/
[highlight.js]: https://highlightjs.org/
[styles]: https://highlightjs.org/static/demo/
[setup-GA4]: https://support.google.com/analytics/answer/9304153?hl=en&ref_topic=9303319
[upgrade-GA4]: https://support.google.com/analytics/answer/9744165?hl=en&ref_topic=9303319
[Read the Docs]: https://readthedocs.org/
[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
[catalog]: https://github.com/mkdocs/catalog#-theming
[localizing your theme]: localizing-your-theme.md

8
.ai/skills/mkdocs/references/upstream/mkdocs-1.6.1-docs/user-guide/cli.md Normal file
View File

@@ -0,0 +1,8 @@
# Command Line Interface
::: mkdocs-click
:module: mkdocs.__main__
:command: cli
:prog_name: mkdocs
:style: table
:list_subcommands: true

1276
.ai/skills/mkdocs/references/upstream/mkdocs-1.6.1-docs/user-guide/configuration.md Normal file
View File

File diff suppressed because it is too large Load Diff

226
.ai/skills/mkdocs/references/upstream/mkdocs-1.6.1-docs/user-guide/customizing-your-theme.md Normal file
View File

@@ -0,0 +1,226 @@
# Customizing Your Theme
Altering a theme to suit your needs.
---
If you would like to make a few tweaks to an existing theme, there is no need
to create your own theme from scratch. For minor tweaks which only require
some CSS and/or JavaScript, you can [use the docs_dir](#using-the-docs_dir).
However, for more complex customizations, including overriding templates, you
will need to [use the theme custom_dir](#using-the-theme-custom_dir) setting.
## Using the docs_dir
The [extra_css] and [extra_javascript] configuration options can be used to
make tweaks and customizations to existing themes. To use these, you simply
need to include either CSS or JavaScript files within your [documentation
directory].
For example, to change the color of the headers in your documentation, create
a file called (for example) `style.css` and place it next to the documentation Markdown. In
that file add the following CSS.
```css
h1 {
color: red;
}
```
Then you need to add it to `mkdocs.yml`:
```yaml
extra_css:
- style.css
```
After making these changes, they should be visible when you run
`mkdocs serve` - if you already had this running, you should see that the CSS
changes were automatically picked up and the documentation will be updated.
NOTE:
Any extra CSS or JavaScript files will be added to the generated HTML
document after the page content. If you desire to include a JavaScript
library, you may have better success including the library by using the
theme [custom_dir].
## Using the theme custom_dir
The [`theme.custom_dir`][custom_dir] configuration option can be used to point
to a directory of files which override the files in a parent theme. The parent
theme would be the theme defined in the [`theme.name`][name] configuration
option. Any file in the `custom_dir` with the same name as a file in the
parent theme will replace the file of the same name in the parent theme. Any
additional files in the `custom_dir` will be added to the parent theme. The
contents of the `custom_dir` should mirror the directory structure of the
parent theme. You may include templates, JavaScript files, CSS files, images,
fonts, or any other media included in a theme.
NOTE:
For this to work, the `theme.name` setting must be set to a known
installed theme. If the `name` setting is instead set to `null` (or not
defined), then there is no theme to override and the contents of the
`custom_dir` must be a complete, standalone theme. See the [Theme
Developer Guide][custom theme] for more information.
For example, the [mkdocs] theme ([browse source]), contains the following
directory structure (in part):
```text
- css\
- fonts\
- img\
- favicon.ico
- grid.png
- js\
- 404.html
- base.html
- content.html
- nav-sub.html
- nav.html
- toc.html
```
To override any of the files contained in that theme, create a new directory
next to your `docs_dir`:
```bash
mkdir custom_theme
```
And then point your `mkdocs.yml` configuration file at the new directory:
```yaml
theme:
name: mkdocs
custom_dir: custom_theme/
```
To override the 404 error page ("file not found"), add a new template file named
`404.html` to the `custom_theme` directory. For information on what can be
included in a template, review the [Theme Developer Guide][custom theme].
To override the favicon, you can add a new icon file at
`custom_theme/img/favicon.ico`.
To include a JavaScript library, copy the library to the `custom_theme/js/`
directory.
Your directory structure should now look like this:
```text
- docs/
- index.html
- custom_theme/
- img/
- favicon.ico
- js/
- somelib.js
- 404.html
- config.yml
```
NOTE:
Any files included in the parent theme (defined in `name`) but not
included in the `custom_dir` will still be utilized. The `custom_dir` will
only override/replace files in the parent theme. If you want to remove
files, or build a theme from scratch, then you should review the [Theme
Developer Guide][custom theme].
### Overriding Template Blocks
The built-in themes implement many of their parts inside template blocks which
can be individually overridden in the `main.html` template. Simply create a
`main.html` template file in your `custom_dir` and define replacement blocks
within that file. Just make sure that the `main.html` extends `base.html`. For
example, to alter the title of the MkDocs theme, your replacement `main.html`
template would contain the following:
```django
{% extends "base.html" %}
{% block htmltitle %}
<title>Custom title goes here</title>
{% endblock %}
```
In the above example, the `htmltitle` block defined in your custom `main.html` file
will be used in place of the default `htmltitle` block defined in the parent theme.
You may re-define as many blocks as you desire, as long as those blocks are
defined in the parent. For example, you could replace the Google Analytics
script with one for a different service or replace the search feature with your
own. You will need to consult the parent theme you are using to determine what
blocks are available to override. The MkDocs and ReadTheDocs themes provide the
following blocks:
* `site_meta`: Contains meta tags in the document head.
* `htmltitle`: Contains the page title in the document head.
* `styles`: Contains the link tags for stylesheets.
* `libs`: Contains the JavaScript libraries (jQuery, etc) included in the page header.
* `scripts`: Contains JavaScript scripts which should execute after a page loads.
* `analytics`: Contains the analytics script.
* `extrahead`: An empty block in the `<head>` to insert custom tags/scripts/etc.
* `site_name`: Contains the site name in the navigation bar.
* `site_nav`: Contains the site navigation in the navigation bar.
* `search_button`: Contains the search box in the navigation bar.
* `next_prev`: Contains the next and previous buttons in the navigation bar.
* `repo`: Contains the repository link in the navigation bar.
* `content`: Contains the page content and table of contents for the page.
* `footer`: Contains the page footer.
You may need to view the source template files to ensure your modifications will
work with the structure of the site. See [Template Variables] for a list of
variables you can use within your custom blocks. For a more complete
explanation of blocks, consult the [Jinja documentation].
### Combining the custom_dir and Template Blocks
Adding a JavaScript library to the `custom_dir` will make it available, but
won't include it in the pages generated by MkDocs. Therefore, a link needs to
be added to the library from the HTML.
Starting the with directory structure above (truncated):
```text
- docs/
- custom_theme/
- js/
- somelib.js
- config.yml
```
A link to the `custom_theme/js/somelib.js` file needs to be added to the
template. As `somelib.js` is a JavaScript library, it would logically go in the
`libs` block. However, a new `libs` block that only includes the new script will
replace the block defined in the parent template and any links to libraries in
the parent template will be removed. To avoid breaking the template, a
[super block] can be used with a call to `super` from within the block:
```django
{% extends "base.html" %}
{% block libs %}
{{ super() }}
<script src="{{ base_url }}/js/somelib.js"></script>
{% endblock %}
```
Note that the [base_url] template variable was used to ensure that the link is
always relative to the current page.
Now the generated pages will include links to the template provided libraries as
well as the library included in the `custom_dir`. The same would be required for
any additional CSS files included in the `custom_dir`.
[custom theme]: ../dev-guide/themes.md
[extra_css]: ./configuration.md#extra_css
[extra_javascript]: ./configuration.md#extra_javascript
[documentation directory]: ./configuration.md#docs_dir
[custom_dir]: ./configuration.md#custom_dir
[name]: ./configuration.md#name
[mkdocs]: ./choosing-your-theme.md#mkdocs
[browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs
[Template Variables]: ../dev-guide/themes.md#template-variables
[Jinja documentation]: https://jinja.palletsprojects.com/en/latest/templates/#template-inheritance
[super block]: https://jinja.palletsprojects.com/en/latest/templates/#super-blocks
[base_url]: ../dev-guide/themes.md#base_url

223
.ai/skills/mkdocs/references/upstream/mkdocs-1.6.1-docs/user-guide/deploying-your-docs.md Normal file
View File

@@ -0,0 +1,223 @@
# Deploying your docs
A basic guide to deploying your docs to various hosting providers
---
## GitHub Pages
If you host the source code for a project on [GitHub], you can easily use
[GitHub Pages] to host the documentation for your project. There are two basic
[types of GitHub Pages sites]: Project Pages sites, and User and Organization
Pages sites. They are nearly identical but have some important differences,
which require a different work flow when deploying.
### Project Pages
Project Pages sites are simpler as the site files get deployed to a branch
within the project repository (`gh-pages` by default). After you `checkout` the
primary working branch (usually `master`) of the git repository where you
maintain the source documentation for your project, run the following command:
```sh
mkdocs gh-deploy
```
That's it! Behind the scenes, MkDocs will build your docs and use the
[ghp-import] tool to commit them to the `gh-pages` branch and push the
`gh-pages` branch to GitHub.
Use `mkdocs gh-deploy --help` to get a full list of options available for the
`gh-deploy` command.
Be aware that you will not be able to review the built site before it is pushed
to GitHub. Therefore, you may want to verify any changes you make to the docs
beforehand by using the `build` or `serve` commands and reviewing the built
files locally.
WARNING:
You should never edit files in your pages repository by hand if you're using
the `gh-deploy` command because you will lose your work the next time you
run the command.
WARNING:
If there are untracked files or uncommitted work in the local repository where
`mkdocs gh-deploy` is run, these will be included in the pages that are deployed.
### Organization and User Pages
User and Organization Pages sites are not tied to a specific project, and the
site files are deployed to the `master` branch in a dedicated repository named
with the GitHub account name. Therefore, you need working copies of two
repositories on our local system. For example, consider the following file
structure:
```text
my-project/
mkdocs.yml
docs/
orgname.github.io/
```
After making and verifying updates to your project you need to change
directories to the `orgname.github.io` repository and call the
`mkdocs gh-deploy` command from there:
```sh
cd ../orgname.github.io/
mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master
```
Note that you need to explicitly point to the `mkdocs.yml` configuration file as
it is no longer in the current working directory. You also need to inform the
deploy script to commit to the `master` branch. You may override the default
with the [remote_branch] configuration setting, but if you forget to change
directories before running the deploy script, it will commit to the `master`
branch of your project, which you probably don't want.
### Custom Domains
GitHub Pages includes support for using a [Custom Domain] for your site. In
addition to the steps documented by GitHub, you need to take one additional step
so that MkDocs will work with your custom domain. You need to add a `CNAME` file
to the root of your [docs_dir]. The file must contain a single bare domain or
subdomain on a single line (see MkDocs' own [CNAME file] as an example). You may
create the file manually, or use GitHub's web interface to set up the custom
domain (under Settings / Custom Domain). If you use the web interface, GitHub
will create the `CNAME` file for you and save it to the root of your "pages"
branch. So that the file does not get removed the next time you deploy, you need
to copy the file to your `docs_dir`. With the file properly included in your
`docs_dir`, MkDocs will include the file in your built site and push it to your
"pages" branch each time you run the `gh-deploy` command.
If you are having problems getting a custom domain to work, see GitHub's
documentation on [Troubleshooting custom domains].
[GitHub]: https://github.com/
[GitHub Pages]: https://pages.github.com/
[types of GitHub Pages sites]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
[ghp-import]: https://github.com/davisp/ghp-import
[remote_branch]: ./configuration.md#remote_branch
[Custom Domain]: https://help.github.com/articles/adding-or-removing-a-custom-domain-for-your-github-pages-site
[docs_dir]: ./configuration.md#docs_dir
[CNAME file]: https://github.com/mkdocs/mkdocs/blob/master/docs/CNAME
[Troubleshooting custom domains]: https://help.github.com/articles/troubleshooting-custom-domains/
## Read the Docs
[Read the Docs][rtd] offers free documentation hosting. You can import your docs
using the Git version control system. Read the Docs supports MkDocs out-of-the-box.
Follow the [instructions] on their site to arrange the files in your repository properly,
create an account and point it at your publicly hosted repository. If properly
configured, your documentation will update each time you push commits to your
public repository.
[rtd]: https://readthedocs.org/
[instructions]: https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html
## Other Providers
Any hosting provider which can serve static files can be used to serve
documentation generated by MkDocs. While it would be impossible to document how
to upload the docs to every hosting provider out there, the following guidelines
should provide some general assistance.
When you build your site (using the `mkdocs build` command), all of the files
are written to the directory assigned to the [site_dir] configuration option
(defaults to `"site"`) in your `mkdocs.yaml` config file. Generally, you will
simply need to copy the contents of that directory to the root directory of your
hosting provider's server. Depending on your hosting provider's setup, you may
need to use a graphical or command line [ftp], [ssh] or [scp] client to transfer
the files.
For example, a typical set of commands from the command line might look
something like this:
```sh
mkdocs build
scp -r ./site user@host:/path/to/server/root
```
Of course, you will need to replace `user` with the username you have with your
hosting provider and `host` with the appropriate domain name. Additionally, you
will need to adjust the `/path/to/server/root` to match the configuration of
your hosts' file system.
[ftp]: https://en.wikipedia.org/wiki/File_Transfer_Protocol
[ssh]: https://en.wikipedia.org/wiki/Secure_Shell
[scp]: https://en.wikipedia.org/wiki/Secure_copy
See your host's documentation for specifics. You will likely want to search
their documentation for "ftp" or "uploading site".
## Local Files
Rather than hosting your documentation on a server, you may instead distribute
the files directly, which can then be viewed in a browser using the `file://`
scheme.
Note that, due to the security settings of all modern browsers, some things
will not work the same and some features may not work at all. In fact, a few
settings will need to be customized in very specific ways.
- [site_url]:
The `site_url` must be set to an empty string, which instructs MkDocs to
build your site so that it will work with the `file://` scheme.
```yaml
site_url: ""
```
- [use_directory_urls]:
Set `use_directory_urls` to `false`. Otherwise, internal links between
pages will not work properly.
```yaml
use_directory_urls: false
```
- [search]:
You will need to either disable the search plugin, or use a third-party
search plugin which is specifically designed to work with the `file://`
scheme. To disable all plugins, set the `plugins` setting to an empty list.
```yaml
plugins: []
```
If you have other plugins enabled, simply ensure that `search` is not
included in the list.
When writing your documentation, it is imperative that all internal links use
relative URLs as [documented][internal links]. Remember, each reader of your
documentation will be using a different device and the files will likely be in a
different location on that device.
If you expect your documentation to be viewed off-line, you may also need to be
careful about which themes you choose. Many themes make use of CDNs for various
support files, which require a live Internet connection. You will need to choose
a theme which includes all support files directly in the theme.
When you build your site (using the `mkdocs build` command), all of the files
are written to the directory assigned to the [site_dir] configuration option
(defaults to `"site"`) in your `mkdocs.yaml` config file. Generally, you will
simply need to copy the contents of that directory and distribute it to your
readers. Alternatively, you may choose to use a third party tool to convert the
HTML files to some other documentation format.
## 404 Pages
When MkDocs builds the documentation it will include a 404.html file in the
[build directory][site_dir]. This file will be automatically used when
deploying to [GitHub](#github-pages) but only on a custom domain. Other web
servers may be configured to use it but the feature won't always be available.
See the documentation for your server of choice for more information.
[site_dir]: ./configuration.md#site_dir
[site_url]: ./configuration.md#site_url
[use_directory_urls]: ./configuration.md#use_directory_urls
[search]: ./configuration.md#search
[internal links]: ./writing-your-docs.md#internal-links

107
.ai/skills/mkdocs/references/upstream/mkdocs-1.6.1-docs/user-guide/installation.md Normal file
View File

@@ -0,0 +1,107 @@
# MkDocs Installation
A detailed guide.
---
## Requirements
MkDocs requires a recent version of [Python] and the Python package
manager, [pip], to be installed on your system.
You can check if you already have these installed from the command line:
```console
$ python --version
Python 3.8.2
$ pip --version
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)
```
If you already have those packages installed, you may skip down to [Installing
MkDocs](#installing-mkdocs).
### Installing Python
Install [Python] using your package manager of choice, or by downloading an
installer appropriate for your system from [python.org] and running it.
> NOTE:
> If you are installing Python on Windows, be sure to check the box to have
> Python added to your PATH if the installer offers such an option (it's
> normally off by default).
>
> ![Add Python to PATH](../img/win-py-install.png)
### Installing pip
If you're using a recent version of Python, the Python package manager, [pip],
is most likely installed by default. However, you may need to upgrade pip to the
lasted version:
```bash
pip install --upgrade pip
```
If you need to install pip for the first time, download [get-pip.py].
Then run the following command to install it:
```bash
python get-pip.py
```
## Installing MkDocs
Install the `mkdocs` package using pip:
```bash
pip install mkdocs
```
You should now have the `mkdocs` command installed on your system. Run `mkdocs
--version` to check that everything worked okay.
```console
$ mkdocs --version
mkdocs, version 1.2.0 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8)
```
> NOTE:
> If you would like manpages installed for MkDocs, the [click-man] tool can
> generate and install them for you. Simply run the following two commands:
>
> ```bash
> pip install click-man
> click-man --target path/to/man/pages mkdocs
> ```
>
> See the [click-man documentation] for an explanation of why manpages are
> not automatically generated and installed by pip.
<!-- -->
> NOTE:
> If you are using Windows, some of the above commands may not work
> out-of-the-box.
>
> A quick solution may be to preface every Python command with `python -m`
> like this:
>
> ```bash
> python -m pip install mkdocs
> python -m mkdocs
> ```
>
> For a more permanent solution, you may need to edit your `PATH` environment
> variable to include the `Scripts` directory of your Python installation.
> Recent versions of Python include a script to do this for you. Navigate to
> your Python installation directory (for example `C:\Python38\`), open the
> `Tools`, then `Scripts` folder, and run the `win_add2path.py` file by double
> clicking on it. Alternatively, you can download the [script][a2p] and run it
> (`python win_add2path.py`).
[Python]: https://www.python.org/
[python.org]: https://www.python.org/downloads/
[pip]: https://pip.readthedocs.io/en/stable/installing/
[get-pip.py]: https://bootstrap.pypa.io/get-pip.py
[click-man]: https://github.com/click-contrib/click-man
[click-man documentation]: https://github.com/click-contrib/click-man#automatic-man-page-installation-with-setuptools-and-pip
[a2p]: https://github.com/python/cpython/blob/master/Tools/scripts/win_add2path.py

63
.ai/skills/mkdocs/references/upstream/mkdocs-1.6.1-docs/user-guide/localizing-your-theme.md Normal file
View File

@@ -0,0 +1,63 @@
# Localizing Your Theme
Display your theme in your preferred language.
---
NOTE:
Theme localization only translates the text elements of the theme itself
(such as "next" and "previous" links), not the actual content of your
documentation. If you wish to create multilingual documentation, you need
to combine theme localization as described here with a third-party
internationalization/localization plugin.
## Installation
For theme localization to work, you must use a theme which supports it and
enable `i18n` (internationalization) support by installing `mkdocs[i18n]`:
```bash
pip install 'mkdocs[i18n]'
```
## Supported locales
In most cases a locale is designated by the [ISO-639-1] (2-letter) abbreviation
for your language. However, a locale may also include a territory (or region or
county) code as well. The language and territory must be separated by an
underscore. For example, some possible locales for English might include `en`,
`en_AU`, `en_GB`, and `en_US`.
For a list of locales supported by the theme you are using, see that theme's
documentation.
- [mkdocs](choosing-your-theme.md#mkdocs-locale)
- [readthedocs](choosing-your-theme.md#readthedocs-locale)
WARNING:
If you configure a language locale which is not yet supported by the theme
that you are using, MkDocs will fall back to the theme's default locale.
## Usage
To specify the locale that MkDocs should use, set the [locale]
parameter of the [theme] configuration option to the appropriate code.
For example, to build the `mkdocs` theme in French you would use the following
in your `mkdocs.yml` configuration file:
```yaml
theme:
name: mkdocs
locale: fr
```
## Contributing theme translations
If a theme has not yet been translated into your language, feel free to
contribute a translation using the [Translation Guide].
[Translation Guide]: ../dev-guide/translations.md
[locale]: configuration.md#locale
[theme]: configuration.md#theme
[ISO-639-1]: https://en.wikipedia.org/wiki/ISO_639-1

540
.ai/skills/mkdocs/references/upstream/mkdocs-1.6.1-docs/user-guide/writing-your-docs.md Normal file
View File

@@ -0,0 +1,540 @@
# Writing your docs
How to layout and write your Markdown source files.
---
## File layout
Your documentation source should be written as regular Markdown files (see
[Writing with Markdown](#writing-with-markdown) below), and placed in the
[documentation directory](configuration.md#docs_dir). By default, this directory
will be named `docs` and will exist at the top level of your project, alongside
the `mkdocs.yml` configuration file.
The simplest project you can create will look something like this:
```text
mkdocs.yml
docs/
index.md
```
By convention your project homepage should be named `index.md` (see [Index
pages](#index-pages) below for details). Any of the following file
extensions may be used for your Markdown source files: `markdown`, `mdown`,
`mkdn`, `mkd`, `md`. All Markdown files included in your documentation
directory will be rendered in the built site regardless of any settings.
NOTE:
Files and directories with names which begin with a dot (for example: `.foo.md` or `.bar/baz.md`) are ignored by MkDocs. This can be overridden with the [`exclude_docs` config](configuration.md#exclude_docs).
You can also create multi-page documentation, by creating several Markdown
files:
```text
mkdocs.yml
docs/
index.md
about.md
license.md
```
The file layout you use determines the URLs that are used for the generated
pages. Given the above layout, pages would be generated for the following URLs:
```text
/
/about/
/license/
```
You can also include your Markdown files in nested directories if that better
suits your documentation layout.
```text
docs/
index.md
user-guide/getting-started.md
user-guide/configuration-options.md
license.md
```
Source files inside nested directories will cause pages to be generated with
nested URLs, like so:
```text
/
/user-guide/getting-started/
/user-guide/configuration-options/
/license/
```
Any files which are not identified as Markdown files (by their file extension)
within the [documentation directory](configuration.md#docs_dir) are copied by
MkDocs to the built site unaltered. See
[how to link to images and media](#linking-to-images-and-media) below for details.
### Index pages
When a directory is requested, by default, most web servers will return an index
file (usually named `index.html`) contained within that directory if one exists.
For that reason, the homepage in all of the examples above has been named
`index.md`, which MkDocs will render to `index.html` when building the site.
Many repository hosting sites provide special treatment for README files by
displaying the contents of the README file when browsing the contents of a
directory. Therefore, MkDocs will allow you to name your index pages as
`README.md` instead of `index.md`. In that way, when users are browsing your
source code, the repository host can display the index page of that directory as
it is a README file. However, when MkDocs renders your site, the file will be
renamed to `index.html` so that the server will serve it as a proper index file.
If both an `index.md` file and a `README.md` file are found in the same
directory, then the `index.md` file is used and the `README.md` file is
ignored.
### Configure Pages and Navigation
The [nav](configuration.md#nav) configuration setting in your `mkdocs.yml` file
defines which pages are included in the global site navigation menu as well as
the structure of that menu. If not provided, the navigation will be
automatically created by discovering all the Markdown files in the
[documentation directory](configuration.md#docs_dir). An automatically created
navigation configuration will always be sorted alphanumerically by file name
(except that index files will always be listed first within a sub-section). You
will need to manually define your navigation configuration if you would like
your navigation menu sorted differently.
A minimal navigation configuration could look like this:
```yaml
nav:
- index.md
- about.md
```
All paths in the navigation configuration must be relative to the `docs_dir`
configuration option. If that option is set to the default value, `docs`, the
source files for the above configuration would be located at `docs/index.md` and
`docs/about.md`.
The above example will result in two navigation items being created at the top
level and with their titles inferred from the contents of the Markdown file or,
if no title is defined within the file, of the file name. To override the title
in the `nav` setting add a title right before the filename.
```yaml
nav:
- Home: index.md
- About: about.md
```
Note that if a title is defined for a page in the navigation, that title will be
used throughout the site for that page and will override any title defined
within the page itself.
Navigation sub-sections can be created by listing related pages together under a
section title. For example:
```yaml
nav:
- Home: index.md
- User Guide:
- Writing your docs: writing-your-docs.md
- Styling your docs: styling-your-docs.md
- About:
- License: license.md
- Release Notes: release-notes.md
```
With the above configuration we have three top level items: "Home", "User Guide"
and "About." "Home" is a link to the homepage for the site. Under the "User
Guide" section two pages are listed: "Writing your docs" and "Styling your
docs." Under the "About" section two more pages are listed: "License" and
"Release Notes."
Note that a section cannot have a page assigned to it. Sections are only
containers for child pages and sub-sections. You may nest sections as deeply as
you like. However, be careful that you don't make it too difficult for your
users to navigate through the site navigation by over-complicating the nesting.
While sections may mirror your directory structure, they do not have to.
Any pages not listed in your navigation configuration will still be rendered and
included with the built site, however, they will not be linked from the global
navigation and will not be included in the `previous` and `next` links. Such
pages will be "hidden" unless linked to directly.
## Writing with Markdown
MkDocs pages must be authored in [Markdown][md], a lightweight markup language
which results in easy-to-read, easy-to-write plain text documents that can be
converted to valid HTML documents in a predictable manner.
MkDocs uses the [Python-Markdown] library to render Markdown documents to HTML.
Python-Markdown is almost completely compliant with the [reference
implementation][md], although there are a few very minor [differences].
In addition to the base Markdown [syntax] which is common across all Markdown
implementations, MkDocs includes support for extending the Markdown syntax with
Python-Markdown [extensions]. See the MkDocs' [markdown_extensions]
configuration setting for details on how to enable extensions.
MkDocs includes some extensions by default, which are highlighted below.
[Python-Markdown]: https://python-markdown.github.io/
[md]: https://daringfireball.net/projects/markdown/
[differences]: https://python-markdown.github.io/#differences
[syntax]: https://daringfireball.net/projects/markdown/syntax
[extensions]: https://python-markdown.github.io/extensions/
[markdown_extensions]: configuration.md#markdown_extensions
### Internal links
MkDocs allows you to interlink your documentation by using regular Markdown
[links]. However, there are a few additional benefits to formatting those links
specifically for MkDocs as outlined below.
[links]: https://daringfireball.net/projects/markdown/syntax#link
#### Linking to pages
When linking between pages in the documentation you can simply use the regular
Markdown [linking][links] syntax, including the *relative path* to the Markdown
document you wish to link to.
```markdown
Please see the [project license](license.md) for further details.
```
When the MkDocs build runs, these Markdown links will automatically be
transformed into an HTML hyperlink to the appropriate HTML page.
WARNING:
Using absolute paths with links is not officially supported. Relative paths
are adjusted by MkDocs to ensure they are always relative to the page. Absolute
paths are not modified at all. This means that your links using absolute paths
might work fine in your local environment but they might break once you deploy
them to your production server.
If the target documentation file is in another directory you'll need to make
sure to include any relative directory path in the link.
```markdown
Please see the [project license](../about/license.md) for further details.
```
The [toc] extension is used by MkDocs to generate an ID for every header in your
Markdown documents. You can use that ID to link to a section within a target
document by using an anchor link. The generated HTML will correctly transform
the path portion of the link, and leave the anchor portion intact.
```markdown
Please see the [project license](about.md#license) for further details.
```
Note that IDs are created from the text of a header. All text is converted to
lowercase and any disallowed characters, including white-space, are converted to
dashes. Consecutive dashes are then reduced to a single dash.
There are a few configuration settings provided by the toc extension which you
can set in your `mkdocs.yml` configuration file to alter the default behavior:
* **`permalink`**
Generate permanent links at the end of each header. Default: `False`.
When set to True the paragraph symbol (&para; or `&para;`) is used as the
link text. When set to a string, the provided string is used as the link
text. For example, to use the hash symbol (`#`) instead, do:
```yaml
markdown_extensions:
- toc:
permalink: "#"
```
* **`baselevel`**
Base level for headers. Default: `1`.
This setting allows the header levels to be automatically adjusted to fit
within the hierarchy of your HTML templates. For example, if the Markdown
text for a page should not contain any headers higher than level 2 (`<h2>`),
do:
```yaml
markdown_extensions:
- toc:
baselevel: 2
```
Then any headers in your document would be increased by 1. For example, the
header `# Header` would be rendered as a level 2 header (`<h2>`) in the HTML
output.
* **`separator`**
Word separator. Default: `-`.
Character which replaces white-space in generated IDs. If you prefer
underscores, then do:
```yaml
markdown_extensions:
- toc:
separator: "_"
```
Note that if you would like to define multiple of the above settings, you must
do so under a single `toc` entry in the `markdown_extensions` configuration
option.
```yml
markdown_extensions:
- toc:
permalink: "#"
baselevel: 2
separator: "_"
```
[toc]: https://python-markdown.github.io/extensions/toc/
#### Linking to images and media
As well as the Markdown source files, you can also include other file types in
your documentation, which will be copied across when generating your
documentation site. These might include images and other media.
For example, if your project documentation needed to include a [GitHub Pages
CNAME file] and a PNG formatted screenshot image then your file layout might
look as follows:
```text
mkdocs.yml
docs/
CNAME
index.md
about.md
license.md
img/
screenshot.png
```
To include images in your documentation source files, simply use any of the
regular Markdown image syntaxes:
```Markdown
Cupcake indexer is a snazzy new project for indexing small cakes.
![Screenshot](img/screenshot.png)
*Above: Cupcake indexer in progress*
```
Your image will now be embedded when you build the documentation, and should
also be previewed if you're working on the documentation with a Markdown editor.
[GitHub Pages CNAME file]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/
#### Linking from raw HTML
Markdown allows document authors to fall back to raw HTML when the Markdown
syntax does not meets the author's needs. MkDocs does not limit Markdown in this
regard. However, as all raw HTML is ignored by the Markdown parser, MkDocs is
not able to validate or convert links contained in raw HTML. When including
internal links within raw HTML, you will need to manually format the link
appropriately for the rendered document.
### Meta-Data
MkDocs includes support for both YAML and MultiMarkdown style meta-data (often
called front-matter). Meta-data consists of a series of keywords and values
defined at the beginning of a Markdown document, which are stripped from the
document prior to it being processing by Python-Markdown. The key/value pairs
are passed by MkDocs to the page template. Therefore, if a theme includes
support, the values of any keys can be displayed on the page or used to control
the page rendering. See your theme's documentation for information about which
keys may be supported, if any.
In addition to displaying information in a template, MkDocs includes support for
a few predefined meta-data keys which can alter the behavior of MkDocs for that
specific page. The following keys are supported:
* **`template`**
The template to use with the current page.
By default, MkDocs uses the `main.html` template of a theme to render
Markdown pages. You can use the `template` meta-data key to define a
different template file for that specific page. The template file must be
available on the path(s) defined in the theme's environment.
* **`title`**
The "title" to use for the document.
MkDocs will attempt to determine the title of a document in the following
ways, in order:
1. A title defined in the [nav] configuration setting for a document.
2. A title defined in the `title` meta-data key of a document.
3. A level 1 Markdown header on the first line of the document body.
([Setext-style] headers are supported *only since MkDocs 1.5*.)
4. The filename of a document.
Upon finding a title for a page, MkDoc does not continue checking any
additional sources in the above list.
[Setext-style]: https://daringfireball.net/projects/markdown/syntax#header
#### YAML Style Meta-Data
YAML style meta-data consists of [YAML] key/value pairs wrapped in YAML style
delimiters to mark the start and/or end of the meta-data. The first line of
a document must be `---`. The meta-data ends at the first line containing an
end deliminator (either `---` or `...`). The content between the delimiters is
parsed as [YAML].
```text
---
title: My Document
summary: A brief description of my document.
authors:
- Waylan Limberg
- Tom Christie
date: 2018-07-10
some_url: https://example.com
---
This is the first paragraph of the document.
```
YAML is able to detect data types. Therefore, in the above example, the values
of `title`, `summary` and `some_url` are strings, the value of `authors` is a
list of strings and the value of `date` is a `datetime.date` object. Note that
the YAML keys are case sensitive and MkDocs expects keys to be all lowercase.
The top level of the YAML must be a collection of key/value pairs, which results
in a Python `dict` being returned. If any other type is returned or the YAML
parser encounters an error, then MkDocs does not recognize the section as
meta-data, the page's `meta` attribute will be empty, and the section is not
removed from the document.
#### MultiMarkdown Style Meta-Data
MultiMarkdown style meta-data uses a format first introduced by the
[MultiMarkdown] project. The data consists of a series of keywords and values
defined at the beginning of a Markdown document, like this:
```text
Title: My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
Tom Christie
Date: January 23, 2018
blank-value:
some_url: https://example.com
This is the first paragraph of the document.
```
The keywords are case-insensitive and may consist of letters, numbers,
underscores and dashes and must end with a colon. The values consist of anything
following the colon on the line and may even be blank.
If a line is indented by 4 or more spaces, that line is assumed to be an
additional line of the value for the previous keyword. A keyword may have as
many lines as desired. All lines are joined into a single string.
The first blank line ends all meta-data for the document. Therefore, the first
line of a document must not be blank.
NOTE:
MkDocs does not support YAML style delimiters (`---` or `...`) for
MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or
absence of the delimiters to determine whether YAML style meta-data or
MultiMarkdown style meta-data is being used. If the delimiters are
detected, but the content between the delimiters is not valid YAML
meta-data, MkDocs does not attempt to parse the content as MultiMarkdown
style meta-data.
[YAML]: https://yaml.org
[MultiMarkdown]: https://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
[nav]: configuration.md#nav
### Tables
The [tables] extension adds a basic table syntax to Markdown which is popular
across multiple implementations. The syntax is rather simple and is generally
only useful for simple tabular data.
A simple table looks like this:
```markdown
First Header | Second Header | Third Header
------------ | ------------- | ------------
Content Cell | Content Cell | Content Cell
Content Cell | Content Cell | Content Cell
```
If you wish, you can add a leading and tailing pipe to each line of the table:
```markdown
| First Header | Second Header | Third Header |
| ------------ | ------------- | ------------ |
| Content Cell | Content Cell | Content Cell |
| Content Cell | Content Cell | Content Cell |
```
Specify alignment for each column by adding colons to separator lines:
```markdown
First Header | Second Header | Third Header
:----------- |:-------------:| -----------:
Left | Center | Right
Left | Center | Right
```
Note that table cells cannot contain any block level elements and cannot contain
multiple lines of text. They can, however, include inline Markdown as defined in
Markdown's [syntax] rules.
Additionally, a table must be surrounded by blank lines. There must be a blank
line before and after the table.
[tables]: https://python-markdown.github.io/extensions/tables/
### Fenced code blocks
The [fenced code blocks] extension adds an alternate method of defining code
blocks without indentation.
The first line should contain 3 or more backtick (`` ` ``) characters, and the
last line should contain the same number of backtick characters (`` ` ``):
````markdown
```
Fenced code blocks are like Standard
Markdown’s regular code blocks, except that
they’re not indented and instead rely on
start and end fence lines to delimit the
code block.
```
````
With this approach, the language can optionally be specified on the first line
after the backticks which informs any syntax highlighters of the language used:
````markdown
```python
def fn():
pass
```
````
Note that fenced code blocks can not be indented. Therefore, they cannot be
nested inside list items, blockquotes, etc.
[fenced code blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/