Skip to content

Commit 06701e2

Browse files
ShahanaFarooquicdecker
ShahanaFarooqui
authored and
cdecker
committed
Add commit shasums and last updated date on documentation site
Note: Some plugins, such as mkdocs-macros-plugin, can retrieve Git details, but they offer limited flexibility in terms of information placement, styling, and formatting. A better approach was to create a custom hook and override the header.
1 parent 4c330ba commit 06701e2

4 files changed

Lines changed: 169 additions & 9 deletions

File tree

‎docs/hooks/git-info.py‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import subprocess
2+
import os
3+
4+
def on_config(config):
5+
"""
6+
Hook to add git commit information. This runs once when MkDocs loads the config.
7+
"""
8+
try:
9+
repo_root = os.path.dirname(os.path.abspath(config.config_file_path))
10+
commit_hash = os.environ.get('DOCS_COMMIT_SHA')
11+
12+
if commit_hash:
13+
print(f"Using commit from DOCS_COMMIT_SHA env: {commit_hash[:7]}")
14+
short_hash = commit_hash[:7]
15+
commit_date = subprocess.check_output(
16+
['git', 'log', '-1', '--format=%cd', '--date=short', commit_hash],
17+
cwd=repo_root,
18+
stderr=subprocess.STDOUT
19+
).decode('utf-8').strip()
20+
print(f"Git hook: Loaded commit info {short_hash} • {commit_date}")
21+
else:
22+
# No commit details in not provided via env
23+
print("DOCS_COMMIT_SHA not set")
24+
25+
# Add to extra context (available in templates if needed)
26+
if 'extra' not in config:
27+
config['extra'] = {}
28+
29+
config['extra']['git'] = {
30+
'commit': commit_hash,
31+
'short_commit': short_hash,
32+
'date': commit_date,
33+
}
34+
35+
except subprocess.CalledProcessError as e:
36+
print(f"Warning: Could not get git information: {e}")
37+
except Exception as e:
38+
print(f"Warning: Error in git hook: {e}")
39+
40+
return config

‎docs/mkdocs.yml‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,10 @@ docs_dir: src
44
repo_url: https://github.com/Blockstream/greenlight
55
edit_uri: tree/main/docs/src
66

7-
plugins:
8-
- search
9-
- social
10-
- redirects:
11-
redirect_maps:
12-
'reference/partner-certs.md': 'getting-started/certs.md'
13-
7+
hooks:
8+
- hooks/git-info.py
9+
extra_css:
10+
- assets/stylesheets/git-info.css
1411
markdown_extensions:
1512
- admonition
1613
- attr_list
@@ -33,6 +30,7 @@ markdown_extensions:
3330
base_path: ["../examples/rust/snippets", "../examples/python/snippets"]
3431
theme:
3532
name: material
33+
custom_dir: overrides
3634
logo: assets/logo.png
3735
favicon: assets/logo.png
3836
palette:
@@ -53,14 +51,13 @@ theme:
5351
toggle:
5452
icon: material/weather-sunny
5553
name: Switch to light mode
56-
5754
features:
5855
- navigation.tabs
59-
- content.code.annotate
6056
- navigation.instant
6157
- navigation.tabs.sticky
6258
- navigation.sections
6359
- navigation.indexes
60+
- content.code.annotate
6461
- content.tabs.link
6562
- content.code.copy
6663

@@ -93,3 +90,7 @@ nav:
9390
- About: about/index.md
9491
- Frequently Asked Questions: about/faq.md
9592
- Changelog: about/changelog.md
93+
extra:
94+
generator: false
95+
copyright: |
96+
© 2024 Greenlight All rights reserved.

‎docs/overrides/partials/header.html‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
{%- set class = "md-header" -%}
2+
{%- if "navigation.tabs.sticky" in features -%}
3+
{%- set class = class ~ " md-header--shadow md-header--lifted" -%}
4+
{%- elif "navigation.tabs" not in features -%}
5+
{%- set class = class ~ " md-header--shadow" -%}
6+
{%- endif -%}
7+
<header class="{{ class }}" data-md-component="header">
8+
<nav class="md-header__inner md-grid" aria-label="{{ lang.t('header') }}">
9+
<a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}" data-md-component="logo">
10+
{% include "partials/logo.html" %}
11+
</a>
12+
<label class="md-header__button md-icon" for="__drawer">
13+
{% set icon = config.theme.icon.menu or "material/menu" %}
14+
{% include ".icons/" ~ icon ~ ".svg" %}
15+
</label>
16+
<div class="md-header__title" data-md-component="header-title">
17+
<div class="md-header__ellipsis">
18+
<div class="md-header__topic">
19+
<span class="md-ellipsis">
20+
{{ config.site_name }}
21+
</span>
22+
</div>
23+
<div class="md-header__topic" data-md-component="header-topic">
24+
<span class="md-ellipsis">
25+
{% if page.meta and page.meta.title %}
26+
{{ page.meta.title }}
27+
{% else %}
28+
{{ page.title }}
29+
{% endif %}
30+
</span>
31+
</div>
32+
</div>
33+
</div>
34+
{% if config.theme.palette %}
35+
{% if not config.theme.palette is mapping %}
36+
{% include "partials/palette.html" %}
37+
{% endif %}
38+
{% endif %}
39+
{% if config.extra.alternate %}
40+
{% include "partials/alternate.html" %}
41+
{% endif %}
42+
{% if "material/search" in config.plugins %}
43+
<label class="md-header__button md-icon" for="__search">
44+
{% set icon = config.theme.icon.search or "material/magnify" %}
45+
{% include ".icons/" ~ icon ~ ".svg" %}
46+
</label>
47+
{% include "partials/search.html" %}
48+
{% endif %}
49+
{% if config.repo_url %}
50+
<div class="md-header__source">
51+
{% include "partials/source.html" %}
52+
{% if config.extra.git %}
53+
<div class="git-info-bar">
54+
<div class="md-grid">
55+
<div class="git-info-item">
56+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor">
57+
<path d="M11.93 8.5a4.002 4.002 0 0 1-7.86 0H.75a.75.75 0 0 1 0-1.5h3.32a4.002 4.002 0 0 1 7.86 0h3.32a.75.75 0 0 1 0 1.5Zm-1.43-.75a2.5 2.5 0 1 0-5 0 2.5 2.5 0 0 0 5 0Z"/>
58+
</svg>
59+
<a href="{{ config.repo_url }}/commit/{{ config.extra.git.commit }}" target="_blank" title="Go to Commit">
60+
{{ config.extra.git.short_commit }}
61+
</a>
62+
</div>
63+
<div class="git-info-item" title="Last Updated">
64+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor">
65+
<path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm7-3.25v2.992l2.028.812a.75.75 0 0 1-.557 1.392l-2.5-1A.751.751 0 0 1 7 8.25v-3.5a.75.75 0 0 1 1.5 0Z"/>
66+
</svg>
67+
{{ config.extra.git.date }}
68+
</div>
69+
</div>
70+
</div>
71+
{% endif %}
72+
</div>
73+
{% endif %}
74+
</nav>
75+
{% if "navigation.tabs.sticky" in features %}
76+
{% if "navigation.tabs" in features %}
77+
{% include "partials/tabs.html" %}
78+
{% endif %}
79+
{% endif %}
80+
</header>
81+
{% if "navigation.tabs" in features %}
82+
{% if "navigation.tabs.sticky" not in features %}
83+
{% include "partials/tabs.html" %}
84+
{% endif %}
85+
{% endif %}

‎docs/src/assets/stylesheets/git-info.css‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.git-info-bar {
2+
font-size: 0.5rem;
3+
}
4+
5+
.git-info-bar .md-grid {
6+
display: flex;
7+
justify-content: center;
8+
align-items: center;
9+
opacity: .75;
10+
}
11+
12+
.git-info-item {
13+
display: flex;
14+
align-items: center;
15+
gap: 0.2rem;
16+
padding-right: 0.3rem;
17+
}
18+
19+
.git-info-item:last-child {
20+
padding-right: 1rem;
21+
}
22+
23+
.git-info-item svg {
24+
width: 0.5rem;
25+
height: 0.5rem;
26+
}
27+
28+
.git-info-item a {
29+
text-decoration: none;
30+
}
31+
32+
.git-info-item a:hover {
33+
text-decoration: none;
34+
}

0 commit comments

Comments
 (0)