Skip to content

Commit ab8d3ab

Browse files
CompEng0001CompEng0001
committed
Merge branch 'mdbook-example'
2 parents 3b7ddae + 512e0a7 commit ab8d3ab

8 files changed

Lines changed: 509 additions & 0 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: deploy to github pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
9+
permissions:
10+
contents: write
11+
12+
jobs:
13+
deploy:
14+
runs-on: ubuntu-24.04
15+
concurrency:
16+
group: ${{ github.workflow }}-${{ github.ref }}
17+
steps:
18+
- uses: actions/checkout@v5
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Set up mdbook (v0.4.52)
23+
run: |
24+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.52/mdbook-v0.4.52-x86_64-unknown-linux-gnu.tar.gz | tar -xz
25+
chmod +x mdbook
26+
mv mdbook ~/.cargo/bin/mdbook
27+
28+
- name: Install mdbook-gitinfo (latest)
29+
run: |
30+
curl -fsSLO https://github.com/CompEng0001/mdbook-gitinfo/releases/latest/download/mdbook-gitinfo-linux.tar.gz
31+
tar -xzf mdbook-gitinfo-linux.tar.gz
32+
mv mdbook-gitinfo-linux ~/.cargo/bin/mdbook-gitinfo
33+
34+
- name: Install mdbook-alerts (v.0.8.0)
35+
run: |
36+
curl -fsSLO https://github.com/lambdalisue/rs-mdbook-alerts/releases/download/v0.8.0/mdbook-alerts-x86_64-unknown-linux-gnu
37+
tar -xzf mdbook-alerts-linux.tar.gz
38+
mv mdbook-alerts-linux ~/.cargo/bin/mdbook-alerts
39+
40+
- name: Show mdbook version
41+
run: mdbook --version
42+
- name: Show gitinfo version
43+
run: mdbook-gitinfo --version
44+
- name: Show alerts version
45+
run: mdbook-alerts --version
46+
47+
- run: mdbook build docs
48+
49+
- name: Deploy to github pages
50+
uses: crazy-max/ghaction-github-pages@v4
51+
with:
52+
target_branch: gh-pages
53+
build_dir: docs/book
54+
jekyll: false
55+
env:
56+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
/target
2+
**/book/*

‎docs/book.toml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
[book]
2+
authors = ["CompEng0001"]
3+
language = "en"
4+
src = "src"
5+
title = "mdbook-gitinfo"
6+
7+
[output.html]
8+
git-repository-url = "https://github.com/compeng0001/mdbook-gitinfo"
9+
edit-url-template = "https://github.com//compeng0001/mdbook-gitinfo/edit/main/{path}"
10+
additional-css = ["theme/pagetoc.css"]
11+
additional-js = ["theme/pagetoc.js"]
12+
13+
[output.html.print]
14+
enable = false
15+
16+
[preprocessor.gitinfo]
17+
enable = true
18+
header = true
19+
footer = true
20+
message.header = "Last updated: <em>{{date}}</em>"
21+
message.footer = "branch: {{branch}} {{sep}} commit: {{hash}} {{sep}} tag: {{tag}}"
22+
align.header = "center"
23+
align.footer = "center"
24+
margin.header.top = "2em"
25+
margin.header.bottom = "2em"
26+
margin.footer = ["2em", "0", "0", "0"]
27+
font-size = "0.8em"
28+
separator = "||"
29+
date-format = "%A %d %B %Y"
30+
time-format = "@ %H:%M:%S"
31+
branch = "main"
32+
hyperlink = true
33+
34+
[preprocessor.alerts]
35+
enable = true

‎docs/src/Documentation.md‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
# Documentation
2+
3+
You can configure options either with dotted keys under `[preprocessor.gitinfo]` or with nested tables such as `[preprocessor.gitinfo.message]`.
4+
Both styles merge as expected, but using one style consistently improves readability.
5+
6+
7+
## 1. Core Behaviour
8+
9+
| Key | Type | Default | Description |
10+
| ----------- | -------- | -------- | ------------------------------------------------------------------------------------ |
11+
| `enable` | `bool` | `true` | Master toggle for the preprocessor. |
12+
| `header` | `bool` | `false` | Render metadata at the top of each page. |
13+
| `footer` | `bool` | `true` | Render metadata at the bottom of each page. |
14+
| `branch` | `string` | `"main"` | Branch to query for commit data. |
15+
| `hyperlink` | `bool` | `false` | Turns commit hash and branch into clickable links (see [Hyperlinks](#4-hyperlinks)). |
16+
17+
18+
## 2. Message Templates
19+
20+
Supported placeholders:
21+
- `{{hash}}` → short commit hash
22+
- `{{long}}` → full commit hash
23+
- `{{tag}}` → lastest tag or user defined - see [Tag](#32-tag)
24+
- `{{date}}` → commit datetime - see [Date and Time](#5-date-and-time)
25+
- `{{sep}}` → separator string - see [Separator](#33-separator)
26+
- `{{branch}}` → branch name as string
27+
28+
29+
Precedence (per placement):
30+
31+
- ` message.both` → `message.header/footer`.
32+
33+
> [!IMPORTANT]
34+
> If a placement-specific template is set (`message.header` or `message.footer`), `message.both` is ignored <em>for that placement</em>.
35+
36+
**Example Dotted keys:**
37+
```toml
38+
[preprocessor.gitinfo]
39+
message.header = "Last updated: <em>{{date}}</em>"
40+
message.footer = "branch: {{branch}}{{sep}}commit: {{hash}}"
41+
message.both = "<em>{{date}}</em>{{sep}}branch: {{branch}}"
42+
```
43+
44+
**Example Table form:**
45+
```toml
46+
[preprocessor.gitinfo.message]
47+
header = "Last updated: <em>{{date}}</em>"
48+
footer = "branch: {{branch}}{{sep}}commit: {{hash}}"
49+
both = "<em>{{date}}</em>{{sep}}branch: {{branch}}"
50+
```
51+
52+
53+
## 3. Formatting and Layout
54+
### 3.1 Font Size
55+
56+
Sets the CSS font size for both header and footer text.
57+
58+
```toml
59+
[preprocessor.gitinfo]
60+
font-size = "0.9em"
61+
```
62+
63+
### 3.2 Tag
64+
65+
Defines the git tag as a string inserted wherever `{{tag}}` appears. By default `tag` is the latest unless specified.
66+
67+
```toml
68+
[preprocessor.gitinfo]
69+
tag = "v1.1.0"
70+
```
71+
72+
### 3.3 Separator
73+
74+
Defines the string inserted wherever `{{sep}}` appears.
75+
76+
```toml
77+
[preprocessor.gitinfo]
78+
separator = " • "
79+
```
80+
81+
### 3.4 Alignment
82+
83+
Values: `"left"` | `"center"` | `"right"`
84+
Default: `"center"` for both header and footer.
85+
86+
> [!IMPORTANT]
87+
> If a alignment-specific template is set (`align.header` or `align.footer`), `align.both` is ignored <em>for that alignment</em>.
88+
89+
**Dotted keys:**
90+
```toml
91+
[preprocessor.gitinfo]
92+
align.header = "left"
93+
align.footer = "right"
94+
align.both = "center"
95+
```
96+
97+
**Table form (equivalent):**
98+
```toml
99+
[preprocessor.gitinfo.align]
100+
both = "center"
101+
header = "left"
102+
footer = "right"
103+
```
104+
105+
### 3.5 Margin (TRBL)
106+
107+
Margins accept CSS-style **T**op-**R**ight-**B**ottom-**L**eft values.
108+
109+
Forms accepted:
110+
111+
- Single value (applies to all sides)
112+
113+
- Array of 1–4 values (CSS shorthand)
114+
115+
- Object with named sides (top, right, bottom, left)
116+
117+
Defaults:
118+
119+
- Header → `["0", "0", "2em", "0"]`
120+
121+
- Footer → `["2em", "0", "0", "0"]`
122+
123+
**Example Dotted keys (array shorthand):**
124+
```toml
125+
[preprocessor.gitinfo]
126+
margin.header = ["0", "0", "1.25em", "0"]
127+
margin.footer = ["2em", "0", "0", "0"]
128+
margin.both = "1em"
129+
```
130+
131+
**Example Dotted keys (named sides):**
132+
```toml
133+
[preprocessor.gitinfo]
134+
margin.header.top = "5em"
135+
margin.footer.bottom = "2em"
136+
margin.both.left = "0.5em"
137+
```
138+
139+
**Example Table form (equivalent):**
140+
```toml
141+
[preprocessor.gitinfo.margin]
142+
both = ["1em"]
143+
header = ["0", "0", "1.25em", "0"]
144+
footer = { top = "2em" }
145+
```
146+
147+
## 4. Hyperlinks
148+
149+
When `hyperlink = true`, the branch and commit hash become clickable links to the corresponding pages on the detected remote (GitHub).
150+
151+
```toml
152+
[preprocessor.gitinfo]
153+
hyperlink = true
154+
message.footer = "branch {{branch}}{{sep}}commit {{hash}}"
155+
```
156+
157+
> [!NOTE]
158+
> hyperlink is constructed from the repo base name branch → commit hash
159+
160+
## 5. Date and Time
161+
162+
Fine-tune timestamp display with `date-format`, `time-format`, `datetime_format`, and `timezone`.
163+
164+
| Key | Default | Purpose |
165+
| ----------------- | ------------ | ---------------------------------- |
166+
| `date-format` | `"%Y-%m-%d"` | Chrono format for the date. |
167+
| `time-format` | `"%H:%M:%S"` | Chrono format for the time. |
168+
| `datetime_format` | — | Overrides both date and time. |
169+
| `show_offset` | `false` | Append timezone offset if missing. |
170+
| `timezone` | `"local"` | See below for modes. |
171+
172+
```toml
173+
[preprocessor.gitinfo]
174+
date-format = "%A %d %B %Y"
175+
time-format = "@ %H:%M:%S"
176+
show_offset = true
177+
timezone = "source"
178+
```
179+
180+
> [!IMPORTANT]
181+
> For DateTime format specifiers refer to `chrono`::`format`:
182+
> - [https://docs.rs/chrono/latest/chrono/format/strftime/index.html](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
183+
184+
## 5.1 Timezone
185+
186+
Controls how commit timestamps are rendered.
187+
188+
| Value | Description |
189+
| ------------------------------- | ------------------------------------------ |
190+
| `local` *(default)* | Convert to system local time. |
191+
| `utc` | Convert to Coordinated Universal Time. |
192+
| `source` | Use the commit’s recorded timezone offset. |
193+
| `fixed:+HH:MM` / `fixed:-HH:MM` | Force a fixed offset. |
194+
| `rfc3339` | Render as RFC 3339 timestamp. |
195+
| *anything else* | Emits a warning and falls back to `local`. |
196+
197+
<br>
198+
199+
> [!IMPORTANT]
200+
> The offset is always applied, but not shown unless you include `%z`, `%:z`, or `%Z` in your time-format
201+
202+
## 6. Examples
203+
204+
### Example 1 – Simple Footer
205+
206+
```toml
207+
[preprocessor.gitinfo]
208+
enable = true
209+
footer = true
210+
message.footer = "Updated {{date}} {{sep}} {{hash}}"
211+
align.footer = "center"
212+
```
213+
214+
### Example 2 – Header + Footer with Margins
215+
216+
```toml
217+
[preprocessor.gitinfo]
218+
enable = true
219+
header = true
220+
footer = true
221+
hyperlink = true
222+
font-size = "0.8em"
223+
separator = "||"
224+
branch = "main"
225+
226+
[preprocessor.gitinfo.message]
227+
header = "Last updated: <em>{{date}}</em>"
228+
footer = "branch: {{branch}}{{sep}}commit: {{hash}}"
229+
230+
[preprocessor.gitinfo.align]
231+
header = "left"
232+
footer = "right"
233+
234+
[preprocessor.gitinfo.margin]
235+
header = { top = "2em", bottom = "1em" }
236+
footer = ["2em", "0", "0", "0"]
237+
```

‎docs/src/Introduction.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Welcome to mdbook-qitinfo
2+
3+
<p align="center">
4+
<a href="https://crates.io/crates/mdbook-gitinfo">
5+
<img src="https://img.shields.io/crates/v/mdbook-gitinfo?style=for-the-badge" alt="Crates.io version" />
6+
</a>
7+
<a href="https://crates.io/crates/mdbook-gitinfo">
8+
<img src="https://img.shields.io/crates/d/mdbook-gitinfo?style=for-the-badge" alt="Downloads" />
9+
</a>
10+
<a href="https://docs.rs/mdbook-gitinfo">
11+
<img src="https://img.shields.io/docsrs/mdbook-gitinfo?style=for-the-badge" alt="Docs.rs" />
12+
</a>
13+
<a href="https://github.com/CompEng0001/mdbook-gitinfo/actions">
14+
<img src="https://img.shields.io/github/actions/workflow/status/CompEng0001/mdbook-gitinfo/release.yml?&style=for-the-badge&label=CI" alt="CI status" />
15+
</a>
16+
</p>
17+
18+
An <a href="https://github.com/rust-lang/mdBook">mdBook</a> preprocessor that injects Git metadata (commit hash, full hash, tag, date/time, branch) into each chapter — as a header, a footer, or both — with flexible templates, alignment, and CSS-style margins.
19+
20+
> [!WARNING]
21+
> Due to break in changes currently mdbook-gitinfo works with mdbook v0.4.52, **not** 0.5.0.
22+
> - [https://crates.io/crates/mdbook/0.4.52](https://crates.io/crates/mdbook/0.4.52)
23+
> - [https://github.com/rust-lang/mdBook/releases/tag/v0.4.52](https://github.com/rust-lang/mdBook/releases/tag/v0.4.52)
24+
25+
<br>
26+
27+
For all options see [Documentation](./Documentation.md) chapter.
28+
29+
## Live Configuration Example
30+
31+
As seen from this page the current preprocessor configuration is:
32+
33+
```toml
34+
[preprocessor.gitinfo]
35+
enable = true
36+
header = true
37+
footer = true
38+
message.header = "Last updated: <em>{{date}}</em>"
39+
message.footer = "branch: {{branch}} {{sep}} commit: {{hash}} {{sep}} tag: {{tag}}"
40+
align.header = "center"
41+
align.footer = "center"
42+
margin.header.top = "2em"
43+
margin.header.bottom = "2em"
44+
margin.footer = ["2em", "0", "0", "0"]
45+
font-size = "0.8em"
46+
separator = "||"
47+
date-format = "%A %d %B %Y"
48+
time-format = "@ %H:%M:%S"
49+
branch = "main"
50+
hyperlink = true
51+
```

‎docs/src/SUMMARY.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Summary
2+
3+
- [Introduction](./Introduction.md)
4+
- [Documentation](./Documentation.md)

0 commit comments

Comments
 (0)