Repository¶

If your documentation is related to source code, Zensical provides the ability to display information about the project's repository as part of the static site, including stars and forks.

Configuration¶

In order to display a link to the repository of your project as part of your documentation, set repo_url in your configuration to the public URL of your repository, e.g.:

[project]
repo_url = "https://github.com/zensical/zensical"

repo_url: https://github.com/zensical/zensical

The link to the repository will be rendered next to the search bar on big screens. Additionally, for public repositories hosted on GitHub or GitLab, the latest release tag¹, as well as the number of stars and forks, are automatically requested and rendered.

Repository name¶

Zensical 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 in your configuration:

[project]
repo_name = "zensical/zensical"

repo_name: zensical/zensical

Repository icon¶

While the default repository icon is a generic git icon, it can be set to any icon bundled with the theme by referencing a valid icon path in mkdocs.yml:

theme:
  icon:
    repo: fontawesome/brands/git-alt

You can use icons from any of the [available icon sets] or use one of these popular choices:

• – fontawesome/brands/git
• – fontawesome/brands/git-alt
• – fontawesome/brands/github
• – fontawesome/brands/github-alt
• – fontawesome/brands/gitlab
• – fontawesome/brands/gitkraken
• – fontawesome/brands/bitbucket

Code actions¶

If the repository URL points to a valid GitHub, GitLab or Bitbucket repository, Zensical provides a setting called edit_uri, which resolves to the subfolder where your documentation is hosted.

If your default branch is called main, change the setting to:

[project]
edit_uri = "edit/main/docs/"

edit_uri: edit/main/docs/

After making sure that edit_uri is correctly configured, buttons for code actions can be added. Two types of code actions are supported: edit and view (GitHub only):

[project.theme]
features = [
  "content.action.edit", # Edit this page
  "content.action.view"  # View source of this page
]

theme:
  features:
    - content.action.edit # Edit this page
    - content.action.view  # View source of this page

The icon of the edit and view buttons can be changed with the following lines:

[project.theme.icon]
edit = "material/pencil"
view = "material/eye"

theme:
  icon:
    edit: material/pencil
    view: material/eye