Skip to content

Commit d05fec9

Browse files
MariusStorhaugCopilot
MariusStorhaug
and
Copilot
committed
Make docs pipeline Zensical-only
Remove mkdocs fallback from Build-Site, delete mkdocs fixture configs, and keep zensical.toml as the sole documentation configuration contract. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 0307c0d commit d05fec9

7 files changed

Lines changed: 241 additions & 176 deletions

File tree

‎.github/workflows/Build-Site.yml‎

Lines changed: 32 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -39,13 +39,10 @@ jobs:
3939
name: docs
4040
path: ${{ fromJson(inputs.Settings).WorkingDirectory }}/outputs/docs
4141

42-
- name: Install mkdocs-material
42+
- name: Install Zensical
4343
shell: pwsh
4444
run: |
45-
pip install mkdocs-material
46-
pip install mkdocs-git-authors-plugin
47-
pip install mkdocs-git-revision-date-localized-plugin
48-
pip install mkdocs-git-committers-plugin-2
45+
pip install zensical
4946
5047
- name: Structure site
5148
uses: PSModule/GitHub-Script@8083ec1f733f00357ee4d0db0c6056686e483bc0 # v1.9.0
@@ -111,49 +108,58 @@ jobs:
111108
Write-Host "Readme Target Path: $readmeTargetPath"
112109
}
113110
114-
LogGroup 'Build docs - Create mkdocs.yml' {
111+
LogGroup 'Build docs - Create docs config' {
115112
$rootPath = Split-Path -Path $ModuleSourcePath -Parent
116113
$possiblePaths = @(
117-
'.github/mkdocs.yml',
118-
'docs/mkdocs.yml',
119-
'mkdocs.yml'
114+
'.github/zensical.toml',
115+
'docs/zensical.toml',
116+
'zensical.toml'
120117
)
121118
122-
$mkdocsSourcePath = $null
119+
$docsConfigSourcePath = $null
123120
foreach ($path in $possiblePaths) {
124121
$candidatePath = Join-Path -Path $rootPath -ChildPath $path
125122
if (Test-Path -Path $candidatePath) {
126-
$mkdocsSourcePath = $candidatePath
123+
$docsConfigSourcePath = $candidatePath
127124
break
128125
}
129126
}
130127
131-
if (-not $mkdocsSourcePath) {
132-
throw "Mkdocs source file not found in any of the expected locations: $($possiblePaths -join ', ')"
128+
if (-not $docsConfigSourcePath) {
129+
throw "Documentation config file not found. Expected one of: $($possiblePaths -join ', ')"
133130
}
134131
135-
$mkdocsTargetPath = Join-Path -Path $SiteOutputPath -ChildPath 'mkdocs.yml'
132+
$docsConfigFileName = [System.IO.Path]::GetFileName($docsConfigSourcePath)
133+
$docsConfigTargetPath = Join-Path -Path $SiteOutputPath -ChildPath $docsConfigFileName
136134
137-
Write-Host "Mkdocs Source Path: $mkdocsSourcePath"
138-
Write-Host "Mkdocs Target Path: $mkdocsTargetPath"
135+
Write-Host "Docs Config Source: $docsConfigSourcePath"
136+
Write-Host "Docs Config Target: $docsConfigTargetPath"
139137
140-
$mkdocsContent = Get-Content -Path $mkdocsSourcePath -Raw
141-
$mkdocsContent = $mkdocsContent.Replace('-{{ REPO_NAME }}-', $ModuleName)
142-
$mkdocsContent = $mkdocsContent.Replace('-{{ REPO_OWNER }}-', $env:GITHUB_REPOSITORY_OWNER)
143-
$mkdocsContent | Set-Content -Path $mkdocsTargetPath -Force
144-
Show-FileContent -Path $mkdocsTargetPath
138+
$docsConfigContent = Get-Content -Path $docsConfigSourcePath -Raw
139+
$docsConfigContent = $docsConfigContent.Replace('-{{ REPO_NAME }}-', $ModuleName)
140+
$docsConfigContent = $docsConfigContent.Replace('-{{ REPO_OWNER }}-', $env:GITHUB_REPOSITORY_OWNER)
141+
$docsConfigContent | Set-Content -Path $docsConfigTargetPath -Force
142+
143+
Write-Host "Build Config Type: $docsConfigFileName"
144+
Show-FileContent -Path $docsConfigTargetPath
145145
}
146146
147-
- name: Build mkdocs-material project
147+
- name: Build documentation site with Zensical
148148
working-directory: ${{ fromJson(inputs.Settings).WorkingDirectory }}/outputs/site
149149
shell: pwsh
150150
run: |
151-
LogGroup 'Build docs - mkdocs build - content' {
152-
Show-FileContent -Path mkdocs.yml
151+
if (-not (Test-Path -Path 'zensical.toml')) {
152+
throw "No documentation config file found in outputs/site. Expected zensical.toml."
153+
}
154+
$configFile = 'zensical.toml'
155+
156+
LogGroup 'Build docs - Zensical config content' {
157+
Write-Host "Using config: $configFile"
158+
Show-FileContent -Path $configFile
153159
}
154160
155-
LogGroup 'Build docs - mkdocs build' {
156-
mkdocs build --config-file mkdocs.yml --site-dir ../../_site
161+
LogGroup 'Build docs - Zensical build' {
162+
zensical build --config-file $configFile --site-dir ../../_site
157163
}
158164
159165
- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0

‎.github/zensical.toml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
[project]
2+
site_name = "-{{ REPO_NAME }}-"
3+
repo_name = "-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-"
4+
repo_url = "https://github.com/-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-"
5+
6+
[project.theme]
7+
variant = "classic"
8+
language = "en"
9+
logo = "Assets/icon.png"
10+
favicon = "Assets/icon.png"
11+
features = [
12+
"navigation.instant",
13+
"navigation.instant.progress",
14+
"navigation.indexes",
15+
"navigation.top",
16+
"navigation.tracking",
17+
"navigation.expand",
18+
"search.suggest",
19+
"search.highlight",
20+
"content.code.copy"
21+
]
22+
23+
[[project.theme.palette]]
24+
media = "(prefers-color-scheme)"
25+
toggle.icon = "lucide/sun-moon"
26+
toggle.name = "Switch to dark mode"
27+
28+
[[project.theme.palette]]
29+
media = "(prefers-color-scheme: dark)"
30+
scheme = "slate"
31+
primary = "black"
32+
accent = "green"
33+
toggle.icon = "lucide/moon"
34+
toggle.name = "Switch to light mode"
35+
36+
[[project.theme.palette]]
37+
media = "(prefers-color-scheme: light)"
38+
scheme = "default"
39+
primary = "indigo"
40+
accent = "green"
41+
toggle.icon = "lucide/sun"
42+
toggle.name = "Switch to system preference"
43+
44+
[project.theme.icon]
45+
repo = "fontawesome/brands/github"
46+
47+
[project.markdown_extensions.toc]
48+
permalink = true
49+
50+
[project.markdown_extensions.attr_list]
51+
[project.markdown_extensions.admonition]
52+
[project.markdown_extensions.md_in_html]
53+
[project.markdown_extensions.pymdownx.details]
54+
[project.markdown_extensions.pymdownx.superfences]
55+
56+
[[project.extra.social]]
57+
icon = "fontawesome/brands/discord"
58+
link = "https://discord.gg/jedJWCPAhD"
59+
name = "-{{ REPO_OWNER }}- on Discord"
60+
61+
[[project.extra.social]]
62+
icon = "fontawesome/brands/github"
63+
link = "https://github.com/-{{ REPO_OWNER }}-/"
64+
name = "-{{ REPO_OWNER }}- on GitHub"
65+
66+
[project.extra.consent]
67+
title = "Cookie consent"
68+
description = "We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better."
69+
actions = ["accept", "reject"]

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Process-PSModule is the corner-stone of the PSModule framework — an end-to-end GitHub Actions workflow that builds, tests, versions, documents, and publishes PowerShell modules to the PowerShell Gallery.
44

5+
Documentation site generation is powered by Zensical. Repositories define site configuration in `zensical.toml`.
6+
57
## Documentation
68

79
The full documentation lives on the MSX / Docs site:

‎tests/srcTestRepo/mkdocs.yml‎

Lines changed: 0 additions & 75 deletions
This file was deleted.

‎tests/srcTestRepo/zensical.toml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
[project]
2+
site_name = "-{{ REPO_NAME }}-"
3+
repo_name = "-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-"
4+
repo_url = "https://github.com/-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-"
5+
6+
[project.theme]
7+
variant = "classic"
8+
language = "en"
9+
logo = "Assets/icon.png"
10+
favicon = "Assets/icon.png"
11+
features = [
12+
"navigation.instant",
13+
"navigation.instant.progress",
14+
"navigation.indexes",
15+
"navigation.top",
16+
"navigation.tracking",
17+
"navigation.expand",
18+
"search.suggest",
19+
"search.highlight",
20+
"content.code.copy"
21+
]
22+
23+
[[project.theme.palette]]
24+
media = "(prefers-color-scheme)"
25+
toggle.icon = "lucide/sun-moon"
26+
toggle.name = "Switch to dark mode"
27+
28+
[[project.theme.palette]]
29+
media = "(prefers-color-scheme: dark)"
30+
scheme = "slate"
31+
primary = "black"
32+
accent = "green"
33+
toggle.icon = "lucide/moon"
34+
toggle.name = "Switch to light mode"
35+
36+
[[project.theme.palette]]
37+
media = "(prefers-color-scheme: light)"
38+
scheme = "default"
39+
primary = "indigo"
40+
accent = "green"
41+
toggle.icon = "lucide/sun"
42+
toggle.name = "Switch to system preference"
43+
44+
[project.theme.icon]
45+
repo = "fontawesome/brands/github"
46+
47+
[project.markdown_extensions.toc]
48+
permalink = true
49+
50+
[project.markdown_extensions.attr_list]
51+
[project.markdown_extensions.admonition]
52+
[project.markdown_extensions.md_in_html]
53+
[project.markdown_extensions.pymdownx.details]
54+
[project.markdown_extensions.pymdownx.superfences]
55+
56+
[[project.extra.social]]
57+
icon = "fontawesome/brands/discord"
58+
link = "https://discord.gg/jedJWCPAhD"
59+
name = "-{{ REPO_OWNER }}- on Discord"
60+
61+
[[project.extra.social]]
62+
icon = "fontawesome/brands/github"
63+
link = "https://github.com/-{{ REPO_OWNER }}-/"
64+
name = "-{{ REPO_OWNER }}- on GitHub"
65+
66+
[project.extra.consent]
67+
title = "Cookie consent"
68+
description = "We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better."
69+
actions = ["accept", "reject"]

‎tests/srcWithManifestTestRepo/mkdocs.yml‎

Lines changed: 0 additions & 75 deletions
This file was deleted.

0 commit comments

Comments
 (0)