Skip to content

Commit e65e6c4

Browse files
akremenetskyakremenetsky
committed
docs: migrate from mkdocs-material to zensical
Replace maintenance-mode mkdocs-material with official successor zensical. Includes i18n improvements, theme configuration, and build command updates. Signed-off-by: Anton Kremenetsky <anton.kremenetsky@gmail.com>
1 parent a2ac674 commit e65e6c4

9 files changed

Lines changed: 264 additions & 187 deletions

File tree

‎docs/openapi/openapi.ru.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,39 @@
22

33
Вы можете просмотреть спецификацию OpenAPI для User API здесь:
44

5-
!!swagger openapi_user.yaml!!
5+
<div id="swagger-ui"></div>
6+
7+
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
8+
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
9+
<style>
10+
/* Dark theme support for Swagger UI */
11+
[data-md-color-scheme="slate"] #swagger-ui {
12+
filter: invert(1) hue-rotate(180deg);
13+
}
14+
[data-md-color-scheme="slate"] #swagger-ui .microlight {
15+
filter: invert(1) hue-rotate(180deg);
16+
}
17+
[data-md-color-scheme="slate"] #swagger-ui .swagger-ui svg {
18+
filter: invert(1) hue-rotate(180deg);
19+
}
20+
</style>
21+
22+
<script src="https://unpkg.com/js-yaml@4/dist/js-yaml.min.js"></script>
23+
<script>
24+
fetch('../openapi_user.yaml')
25+
.then(response => response.text())
26+
.then(yamlText => {
27+
const spec = jsyaml.load(yamlText);
28+
SwaggerUIBundle({
29+
spec: spec,
30+
dom_id: '#swagger-ui',
31+
presets: [SwaggerUIBundle.presets.apis],
32+
validatorUrl: null,
33+
tryItOutEnabled: true
34+
});
35+
})
36+
.catch(err => {
37+
console.error('Failed to load spec:', err);
38+
document.getElementById('swagger-ui').innerHTML = '<p>Ошибка загрузки спецификации: ' + err.message + '</p>';
39+
});
40+
</script>

‎docs/openapi/openapi_boot.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,39 @@
22

33
You can view the OpenAPI specification for the Boot API here:
44

5-
!!swagger openapi_boot.yaml!!
5+
<div id="swagger-ui"></div>
6+
7+
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
8+
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
9+
<style>
10+
/* Dark theme support for Swagger UI */
11+
[data-md-color-scheme="slate"] #swagger-ui {
12+
filter: invert(1) hue-rotate(180deg);
13+
}
14+
[data-md-color-scheme="slate"] #swagger-ui .microlight {
15+
filter: invert(1) hue-rotate(180deg);
16+
}
17+
[data-md-color-scheme="slate"] #swagger-ui .swagger-ui svg {
18+
filter: invert(1) hue-rotate(180deg);
19+
}
20+
</style>
21+
22+
<script src="https://unpkg.com/js-yaml@4/dist/js-yaml.min.js"></script>
23+
<script>
24+
fetch('../openapi_boot.yaml')
25+
.then(response => response.text())
26+
.then(yamlText => {
27+
const spec = jsyaml.load(yamlText);
28+
SwaggerUIBundle({
29+
spec: spec,
30+
dom_id: '#swagger-ui',
31+
presets: [SwaggerUIBundle.presets.apis],
32+
validatorUrl: null,
33+
tryItOutEnabled: true
34+
});
35+
})
36+
.catch(err => {
37+
console.error('Failed to load spec:', err);
38+
document.getElementById('swagger-ui').innerHTML = '<p>Error loading API spec: ' + err.message + '</p>';
39+
});
40+
</script>

‎docs/openapi/openapi_orch.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,39 @@
22

33
You can view the OpenAPI specification for the Orch API here:
44

5-
!!swagger openapi_orch.yaml!!
5+
<div id="swagger-ui"></div>
6+
7+
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
8+
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
9+
<style>
10+
/* Dark theme support for Swagger UI */
11+
[data-md-color-scheme="slate"] #swagger-ui {
12+
filter: invert(1) hue-rotate(180deg);
13+
}
14+
[data-md-color-scheme="slate"] #swagger-ui .microlight {
15+
filter: invert(1) hue-rotate(180deg);
16+
}
17+
[data-md-color-scheme="slate"] #swagger-ui .swagger-ui svg {
18+
filter: invert(1) hue-rotate(180deg);
19+
}
20+
</style>
21+
22+
<script src="https://unpkg.com/js-yaml@4/dist/js-yaml.min.js"></script>
23+
<script>
24+
fetch('../openapi_orch.yaml')
25+
.then(response => response.text())
26+
.then(yamlText => {
27+
const spec = jsyaml.load(yamlText);
28+
SwaggerUIBundle({
29+
spec: spec,
30+
dom_id: '#swagger-ui',
31+
presets: [SwaggerUIBundle.presets.apis],
32+
validatorUrl: null,
33+
tryItOutEnabled: true
34+
});
35+
})
36+
.catch(err => {
37+
console.error('Failed to load spec:', err);
38+
document.getElementById('swagger-ui').innerHTML = '<p>Error loading API spec: ' + err.message + '</p>';
39+
});
40+
</script>

‎docs/openapi/openapi_status.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,39 @@
22

33
You can view the OpenAPI specification for the Status API here:
44

5-
!!swagger openapi_status.yaml!!
5+
<div id="swagger-ui"></div>
6+
7+
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
8+
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
9+
<style>
10+
/* Dark theme support for Swagger UI */
11+
[data-md-color-scheme="slate"] #swagger-ui {
12+
filter: invert(1) hue-rotate(180deg);
13+
}
14+
[data-md-color-scheme="slate"] #swagger-ui .microlight {
15+
filter: invert(1) hue-rotate(180deg);
16+
}
17+
[data-md-color-scheme="slate"] #swagger-ui .swagger-ui svg {
18+
filter: invert(1) hue-rotate(180deg);
19+
}
20+
</style>
21+
22+
<script src="https://unpkg.com/js-yaml@4/dist/js-yaml.min.js"></script>
23+
<script>
24+
fetch('../openapi_status.yaml')
25+
.then(response => response.text())
26+
.then(yamlText => {
27+
const spec = jsyaml.load(yamlText);
28+
SwaggerUIBundle({
29+
spec: spec,
30+
dom_id: '#swagger-ui',
31+
presets: [SwaggerUIBundle.presets.apis],
32+
validatorUrl: null,
33+
tryItOutEnabled: true
34+
});
35+
})
36+
.catch(err => {
37+
console.error('Failed to load spec:', err);
38+
document.getElementById('swagger-ui').innerHTML = '<p>Error loading API spec: ' + err.message + '</p>';
39+
});
40+
</script>

‎docs/openapi/openapi_user.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,39 @@
22

33
You can view the OpenAPI specification for the User API here:
44

5-
!!swagger openapi_user.yaml!!
5+
<div id="swagger-ui"></div>
6+
7+
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
8+
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
9+
<style>
10+
/* Dark theme support for Swagger UI */
11+
[data-md-color-scheme="slate"] #swagger-ui {
12+
filter: invert(1) hue-rotate(180deg);
13+
}
14+
[data-md-color-scheme="slate"] #swagger-ui .microlight {
15+
filter: invert(1) hue-rotate(180deg);
16+
}
17+
[data-md-color-scheme="slate"] #swagger-ui .swagger-ui svg {
18+
filter: invert(1) hue-rotate(180deg);
19+
}
20+
</style>
21+
22+
<script src="https://unpkg.com/js-yaml@4/dist/js-yaml.min.js"></script>
23+
<script>
24+
fetch('../openapi_user.yaml')
25+
.then(response => response.text())
26+
.then(yamlText => {
27+
const spec = jsyaml.load(yamlText);
28+
SwaggerUIBundle({
29+
spec: spec,
30+
dom_id: '#swagger-ui',
31+
presets: [SwaggerUIBundle.presets.apis],
32+
validatorUrl: null,
33+
tryItOutEnabled: true
34+
});
35+
})
36+
.catch(err => {
37+
console.error('Failed to load spec:', err);
38+
document.getElementById('swagger-ui').innerHTML = '<p>Error loading API spec: ' + err.message + '</p>';
39+
});
40+
</script>

‎mkdocs.yml‎

Lines changed: 31 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,41 @@
1-
site_name: exordos_core
2-
site_url: https://github.com/infraguys/
1+
site_name: Exordos Core
2+
site_url: https://github.com/exordos/
33
repo_name: exordos_core
4-
repo_url: https://github.com/infraguys/exordos_core
4+
repo_url: https://github.com/exordos/exordos_core
55
edit_uri: browse/docs/
6+
copyright: Copyright &copy; 2025-2026 Genesis Corporation
67

78
theme:
8-
name: material
9+
# variant: modern
10+
name: zensical
11+
variant: modern
912
language: en
1013
features:
1114
- search.suggest
1215
- search.highlight
13-
# to move menu to top uncomment the following lines
14-
# - navigation.tabs
15-
# - navigation.tabs.sticky
16+
- navigation.tabs
17+
- navigation.tabs.sticky
18+
- navigation.sections
19+
- navigation.expand
1620
- toc.integrate
1721
- content.code.copy
1822
palette:
1923
- scheme: default
24+
primary: indigo
2025
toggle:
21-
icon: material/lightbulb-outline
26+
icon: lucide/sun
2227
name: Switch to dark mode
2328
- scheme: slate
29+
primary: indigo
2430
toggle:
25-
icon: material/lightbulb
31+
icon: lucide/moon
2632
name: Switch to light mode
2733

2834
plugins:
2935
- i18n:
3036
docs_structure: suffix
37+
fallback_to: en
38+
# reconfigure_material: true
3139
languages:
3240
- locale: en
3341
default: true
@@ -43,16 +51,26 @@ plugins:
4351
- glightbox
4452
- render_swagger
4553

54+
4655
extra:
4756
repo_icon: github
57+
alternate:
58+
- name: English
59+
link: ./
60+
lang: en
61+
- name: Russian
62+
link: ./index.ru/
63+
lang: ru
4864

4965
markdown_extensions:
5066
- meta
5167
- admonition
5268
- footnotes
5369
- attr_list
54-
- codehilite:
55-
guess_lang: false
70+
- pymdownx.highlight:
71+
anchor_linenums: true
72+
line_spans: __span
73+
pygments_lang_class: true
5674
- toc:
5775
slugify: !!python/name:pymdownx.slugs.uslugify
5876
permalink: '#'
@@ -61,8 +79,8 @@ markdown_extensions:
6179
smart_enable: all
6280
- pymdownx.keys
6381
- pymdownx.emoji:
64-
emoji_index: !!python/name:pymdownx.emoji.gemoji
65-
emoji_generator: !!python/name:pymdownx.emoji.to_svg
82+
emoji_index: !!python/name:zensical.extensions.emoji.twemoji
83+
emoji_generator: !!python/name:zensical.extensions.emoji.to_svg
6684
- pymdownx.caret
6785
- pymdownx.critic
6886
- pymdownx.details

‎pyproject.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,10 +77,10 @@ shellcheck = [
7777
"shellcheck-py",
7878
]
7979
docs = [
80-
"mkdocs-material==9.1.0",
80+
"zensical>=0.0.32",
8181
"mkdocs-glightbox",
8282
"mkdocs-render-swagger-plugin",
83-
"mkdocs-static-i18n[material]"
83+
"mkdocs-static-i18n"
8484
]
8585

8686
[tool.ruff]

‎tox.ini‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,13 +61,13 @@ commands = mypy -p exordos_core
6161
extras =
6262
docs
6363
runner = uv-venv-lock-runner
64-
commands = mkdocs serve --dev-addr 0.0.0.0:8181 --livereload
64+
commands = zensical serve --dev-addr 0.0.0.0:8181
6565

6666
[testenv:docs-deploy]
6767
extras =
6868
docs
6969
runner = uv-venv-lock-runner
70-
commands = mkdocs gh-deploy --force
70+
commands = zensical gh-deploy --force
7171

7272
[testenv:mdlint]
7373
runner = uv-venv-lock-runner

0 commit comments

Comments
 (0)