diff --git a/docs/guides/adding-a-git-repository.md b/docs/guides/adding-a-git-repository.md index 3225705ea..7963eabad 100644 --- a/docs/guides/adding-a-git-repository.md +++ b/docs/guides/adding-a-git-repository.md @@ -4,31 +4,96 @@ template: overrides/main.html # Adding a git repository -- link edit button -- link related source file (via metadata) +If your documentation is related to source code, Material for MkDocs provides +the ability to display information to the project's repository as part of the +static site, including statistics like stars and forks. Furthermore, certain +documents can be linked to specific source files. ## Configuration -To include a link to the repository of your project within your documentation, -set the following variables via your project's `mkdocs.yml`: +In order to display a link to the repository of your project as part of your +documentation, set [`repo_url`][1] in `mkdocs.yml` to the public URL of your +repository, e.g.: ``` yaml -repo_name: squidfunk/mkdocs-material repo_url: https://github.com/squidfunk/mkdocs-material ``` -The name of the repository will be rendered next to the search bar on big +The link to the repository will be rendered next to the search bar on big screens and as part of the main navigation drawer on smaller screen sizes. -Additionally, for GitHub and GitLab, the number of stars and forks is shown. -Note that the repository icon can be explicitly set through `theme.icon.repo`. +Additionally, for GitHub and GitLab, the number of stars and forks is +automatically requested and rendered for _public repositories_. -!!! question "Why is there an edit button at the top of every article?" + [1]: https://www.mkdocs.org/user-guide/configuration/#repo_url - If the `repo_url` is set to a GitHub or BitBucket repository, and the - `repo_name` is set to *GitHub* or *BitBucket* (implied by default), an - edit button will appear at the top of every article. This is the automatic - behavior that MkDocs implements. See the [MkDocs documentation][20] on more - guidance regarding the `edit_uri` attribute, which defines whether the edit - button is shown or not. +### Repository name - [20]: https://www.mkdocs.org/user-guide/configuration/#edit_uri +[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default: +_automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket` + +MkDocs will infer the source provider by examining the URL and try to set the +_repository name_ automatically. If you wish to customize the name, set +[`repo_name`][3] in `mkdocs.yml`: + +``` yaml +repo_name: squidfunk/mkdocs-material +``` + + [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source.html + [3]: https://www.mkdocs.org/user-guide/configuration/#repo_url + +### Repository icon + +[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: +`fontawesome/brands/git-alt` + +While the default _repository icon_ is a generic git icon, it can be set to +[any icon bundled with the theme][4] by referencing a valid icon path in +`mkdocs.yml`: + +``` yaml +theme: + icon: + repo: fontawesome/brands/git-alt +``` + +Some popular repository icons: + +- :fontawesome-brands-git: – `:fontawesome-brands-git:` +- :fontawesome-brands-git-square: – `:fontawesome-brands-git-square:` +- :fontawesome-brands-github: – `:fontawesome-brands-github:` +- :fontawesome-brands-github-alt: – `:fontawesome-brands-github-alt:` +- :fontawesome-brands-github-square: – `:fontawesome-brands-github-square:` +- :fontawesome-brands-gitlab: – `:fontawesome-brands-gitlab:` +- :fontawesome-brands-gitkraken: – `:fontawesome-brands-gitkraken:` +- :fontawesome-brands-bitbucket: – `:fontawesome-brands-bitbucket:` +- :fontawesome-solid-trash: – `:fontawesome-solid-trash:` + + [4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons + +### Edit button + +[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: +_automatically set_ + +If the repository URL points to a [GitHub][6], [GitLab][7] or [Bitbucket][8] +repository, an _edit button_ is displayed at the top of each document. This +behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`: + +=== "Customize edit path" + + ``` yaml + edit_uri: edit/master/docs/ + ``` + +=== "Hide edit button" + + ``` yaml + edit_uri: "" + ``` + + [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L299-L308 + [6]: https://github.com/ + [7]: https://about.gitlab.com/ + [8]: https://bitbucket.org/ + [9]: https://www.mkdocs.org/user-guide/configuration/#edit_uri diff --git a/docs/guides/changing-colors.md b/docs/guides/changing-colors.md index 99e148453..4f28c6ff6 100644 --- a/docs/guides/changing-colors.md +++ b/docs/guides/changing-colors.md @@ -7,7 +7,7 @@ template: overrides/main.html As any good Material Design implementation, Material for MkDocs supports Google's original [color palette][1], which can be easily configured through `mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to -fit your brand identity by using [CSS variables][2]. +fit your brand's identity by using [CSS variables][2]. [1]: http://www.materialui.co/colors [2]: #customization @@ -251,5 +251,5 @@ colors or neutral colors: [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_colors.scss [7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties [8]: ../customization.md#additional-stylesheets - [9]: ../writing/code-blocks.md - [10]: ../writing/admonitions.md + [9]: ../reference/code-blocks.md + [10]: ../reference/admonitions.md diff --git a/docs/guides/changing-the-language.md b/docs/guides/changing-the-language.md index d7886fa5d..7c27029ab 100644 --- a/docs/guides/changing-the-language.md +++ b/docs/guides/changing-the-language.md @@ -14,7 +14,7 @@ search can be configured to use a language-specific stemmer (if available). [:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en` -You can set the language from `mkdocs.yml` with: +You can set the _site language_ from `mkdocs.yml` with: ``` yaml theme: @@ -24,49 +24,49 @@ theme: The following languages are supported: