# Documentation
You can configure options either with dotted keys under `[preprocessor.gitinfo]` or with nested tables such as `[preprocessor.gitinfo.message]`.
Both styles merge as expected, but using one style consistently improves readability.
## 1. Core Behaviour
| `enable` | `bool` | `true` | Master toggle for the preprocessor. |
| `header` | `bool` | `false` | Render metadata at the top of each page. |
| `footer` | `bool` | `true` | Render metadata at the bottom of each page. |
| `branch` | `string` | `"main"` | Branch to query for commit data. |
| `hyperlink` | `bool` | `false` | Turns commit hash and branch into clickable links (see [Hyperlinks](#4-hyperlinks)). |
| `contributors` |`bool` | `false` | Renders Contributors section (see [Contributors](#6-contributors)). |
| `contributor-file` | `string` | *(unset)* | Optional repository-root-relative Markdown file of GitHub usernames; overrides Git shortlog and `contributors-source`. |
## 2. Message Templates
Supported placeholders:
- `{{hash}}` → short commit hash
- `{{long}}` → full commit hash
- `{{tag}}` → lastest tag or user defined - see [Tag](#32-tag)
- `{{date}}` → commit datetime - see [Date and Time](#5-date-and-time)
- `{{sep}}` → separator string - see [Separator](#33-separator)
- `{{branch}}` → branch name as string
Precedence (per placement):
- ` message.both` → `message.header/footer`.
> [!IMPORTANT]
> If a placement-specific template is set (`message.header` or `message.footer`), `message.both` is ignored <em>for that placement</em>.
::: tabs
::: tab label="Example Dotted keys" icon=toml
```toml
[preprocessor.gitinfo]
message.header = "Last updated: <em>{{date}}</em>"
message.footer = "branch: {{branch}}{{sep}}commit: {{hash}}"
message.both = "<em>{{date}}</em>{{sep}}branch: {{branch}}"
```
:::
::: tab label="Example Table form" icon=toml
```toml
[preprocessor.gitinfo.message]
header = "Last updated: <em>{{date}}</em>"
footer = "branch: {{branch}}{{sep}}commit: {{hash}}"
both = "<em>{{date}}</em>{{sep}}branch: {{branch}}"
```
:::
:::
## 3. Formatting and Layout
### 3.1 Font Size
Sets the CSS font size for both header and footer text.
```toml
[preprocessor.gitinfo]
font-size = "0.9em"
```
### 3.2 Tag
Defines the git tag as a string inserted wherever `{{tag}}` appears. By default `tag` is the latest unless specified.
```toml
[preprocessor.gitinfo]
tag = "v1.1.0"
```
### 3.3 Separator
Defines the string inserted wherever `{{sep}}` appears.
```toml
[preprocessor.gitinfo]
separator = " • "
```
### 3.4 Alignment
> [!IMPORTANT]
> If a alignment-specific template is set (`align.header` or `align.footer`), `align.both` is ignored <em>for that alignment</em>.
::: tabs
::: tab label="Dotted keys" icon=toml
```toml
[preprocessor.gitinfo]
align.header = "left"
align.footer = "right"
align.both = "center"
```
:::
::: tab label="Table form (equivalent)" icon=toml
```toml
[preprocessor.gitinfo.align]
both = "center"
header = "left"
footer = "right"
```
:::
:::
### 3.5 Margin (TRBL)
Margins accept CSS-style **T**op-**R**ight-**B**ottom-**L**eft values.
Forms accepted:
- Single value (applies to all sides)
- Array of 1–4 values (CSS shorthand)
- Object with named sides (top, right, bottom, left)
Defaults:
- Header → `["0", "0", "2em", "0"]`
- Footer → `["2em", "0", "0", "0"]`
::: tabs
::: tab label="Dotted keys (array shorthand)" icon=toml
```toml
[preprocessor.gitinfo]
margin.header = ["0", "0", "1.25em", "0"]
margin.footer = ["2em", "0", "0", "0"]
margin.both = "1em"
```
:::
::: tab label="Dotted keys (named sides)" icon=toml
```toml
[preprocessor.gitinfo]
margin.header.top = "5em"
margin.footer.bottom = "2em"
margin.both.left = "0.5em"
```
:::
::: tab label="Table (equivalent)" icon=toml
```toml
[preprocessor.gitinfo.margin]
both = ["1em"]
header = ["0", "0", "1.25em", "0"]
footer = { top = "2em" }
```
:::
:::
## 4. Hyperlinks
When `hyperlink = true`, the branch and commit hash become clickable links to the corresponding pages on the detected remote (GitHub).
```toml
[preprocessor.gitinfo]
hyperlink = true
message.footer = "branch {{branch}}{{sep}}commit {{hash}}"
```
> [!NOTE]
> hyperlink is constructed from the repo base name branch → commit hash
## 5. Date and Time
Fine-tune timestamp display with `date-format`, `time-format`, `datetime_format`, and `timezone`.
| `date-format` | `"%Y-%m-%d"` | Chrono format for the date. |
| `time-format` | `"%H:%M:%S"` | Chrono format for the time. |
| `datetime_format` | — | Overrides both date and time. |
| `show_offset` | `false` | Append timezone offset if missing. |
| `timezone` | `"local"` | See below for modes. |
```toml
[preprocessor.gitinfo]
date-format = "%A %d %B %Y"
time-format = "@ %H:%M:%S"
show_offset = true
timezone = "source"
```
> [!IMPORTANT]
> For DateTime format specifiers refer to `chrono`::`format`:
> - [https://docs.rs/chrono/latest/chrono/format/strftime/index.html](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
## 5.1 Timezone
Controls how commit timestamps are rendered.
| `local` *(default)* | Convert to system local time. |
| `utc` | Convert to Coordinated Universal Time. |
| `source` | Use the commit’s recorded timezone offset. |
| `fixed:+HH:MM` / `fixed:-HH:MM` | Force a fixed offset. |
| `rfc3339` | Render as RFC 3339 timestamp. |
| *anything else* | Emits a warning and falls back to `local`. |
<br>
> [!IMPORTANT]
> The offset is always applied, but not shown unless you include `%z`, `%:z`, or `%Z` in your time-format
## 6. Contributors
Optionally render a contributors block, showing GitHub avatars and profile links for users associated with the book.
This feature is **opt-in** and disabled by default.
```toml
[preprocessor.gitinfo]
contributors = true
```
Contributors are rendered wherever the token appears:
```md
{% contributors %}
```
> [!NOTE]
> Internally, mdbook-gitinfo generates a small CSS file, `gitinfo.css` inside the book’s
> theme override directory and registers it with mdBook, `[output.html.additional-css]`.
> Advanced users may override or extend these styles using their own theme CSS.
### 6.1 Contributor Sources
The source of contributor data is controlled via `contributors-source`.
```toml
[preprocessor.gitinfo]
contributors = true
contributors-source = "git"
```
Supported values:
| `git` | *(default)* Derive contributors from git history using `git shortlog`. |
| `file` | Read contributors from a file at the repository root (e.g. `CONTRIBUTORS.md`). |
| `inline` | Contributors are explicitly listed in the `{% contributors %}` token. |
If `contributors-source` is omitted, it defaults to `"git"`.
### 6.2 `contributors-source = "git"` (default)
Contributors are inferred from the repository’s git history:
```sh
git shortlog -sne --all
```
The author name is treated as a GitHub username and used to construct:
- Profile link: `https://github.com/<username>`
- Avatar image: `https://github.com/<username>.png`
> [!NOTE]
> This approach assumes commit author names match GitHub usernames.
> While this is common (and recommended), it is a best-effort heuristic.
**Token usage**
```md
{% contributors %}
```
Inline usernames are ignored in this mode:
```md
{% contributors author1 authorN %}
```
A warning is emitted if arguments are provided.
### 6.3 `contributors-source = "file"`
Contributors are read from a file located at the repository root
(which may be above the directory containing `book.toml`).
```toml
[preprocessor.gitinfo]
contributors = true
contributors-source = "file"
contributors-file = "CONTRIBUTORS.md"
```
Default file name (if omitted):
```md
CONTRIBUTORS.md
```
**Accepted formats**
Each contributor should appear on its own line:
```
name
name2
name3
```
Bullet prefixes are also accepted:
```
- name
- name2
- name3
```
Blank lines are ignored.
**Simpler override (recommended):** Set `contributor-file` without changing
`contributors-source`. This automatically uses the specified file instead of
`git shortlog`. Relative paths are resolved from the Git repository root,
even if `book.toml` is in a subdirectory. Absolute paths are also supported.
```toml
[preprocessor.gitinfo]
contributors = true
contributor-file = "CONTRIBUTORS.md"
```
The file may contain one GitHub username per line, optionally prefixed by
`- ` or `* `, with blank lines and Markdown headings ignored:
```markdown
# Contributors
- CompEng0001
- ocotocat
```
If the configured file is missing or unreadable, the build reports an error
instead of silently falling back to Git history. Other contributor display
options (title, message, exclusions and maximum visible) still apply.
### 6.4 `contributors-source = "inline"`
Contributors are specified **directly in the token**.
```toml
[preprocessor.gitinfo]
contributors = true
contributors-source = "inline"
```
Usage:
```md
{% contributors name name2 name3 %}
```
If no usernames are provided, nothing is rendered and a warning is emitted.
This mode is intended for:
- curated attribution
- future per-page contributor control
- repositories where git history is not representative
### 6.5 Title, Message, and Exclusions
**Contributor Title**
```toml
[preprocessor.gitinfo]
contributor-title = "Contributors"
```
Default: `"Contributors"`
**Optional Message**
An optional message can be rendered above the avatars.
This supports raw HTML.
```toml
[preprocessor.gitinfo]
contributor-message = "<em>Thanks to all the contributors</em>"
```
**Excluding Contributors**
Usernames can be excluded regardless of source:
```toml
[preprocessor.gitinfo]
exclude-contributors = ["github-actions[bot]", "dependabot"]
```
This is useful for filtering automation accounts or CI bots.
### 6.6 Rendering Behaviour
- The contributors block is rendered as raw HTML
- It is compatible with the HTML renderer
- If contributors are enabled but no valid users are found:
- nothing is rendered
- a warning is emitted
## 7. Examples
::: tabs
::: tab label="Simple Footer" icon=toml
```toml
[preprocessor.gitinfo]
enable = true
footer = true
message.footer = "Updated {{date}} {{sep}} {{hash}}"
align.footer = "center"
```
:::
::: tab label="Header + Footer with Margins" icon=toml
```toml
[preprocessor.gitinfo]
enable = true
header = true
footer = true
hyperlink = true
font-size = "0.8em"
[preprocessor.gitinfo.message]
header = "Last updated: <em>{{date}}</em>"
footer = "branch: {{branch}}{{sep}}commit: {{hash}}"
[preprocessor.gitinfo.align]
header = "left"
footer = "right"
[preprocessor.gitinfo.margin]
header = { top = "2em", bottom = "1em" }
footer = ["2em", "0", "0", "0"]
```
:::
:::