advisoryhub/mkdocs.yml at main · eclipse-csi/advisoryhub · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
# MkDocs configuration for the AdvisoryHub documentation site
# (https://eclipse-csi.github.io/advisoryhub/). Built with mkdocs-material and
# versioned with mike (.github/workflows/docs.yml): one directory per release
# on the gh-pages branch + versions.json; `latest` tracks the newest release,
# `dev` tracks main. README.md files render as section indexes natively.
#
# NOTE: the superfences and toc-slugify settings below use `!!python/name:` /
# `!!python/object/apply:` YAML tags, which safe-load parsers reject —
# mkdocs.yml is excluded from the prek check-yaml hook for that reason.
#
# `strict: true` is deliberately NOT set here so `mkdocs serve` stays
# forgiving while iterating; the `validation:` warnings below are promoted to
# errors by the --strict flag in `mise run docs-build` (the PR and deploy gate).

site_name: AdvisoryHub
site_description: Eclipse Foundation security advisory authoring, review, and publication system
site_url: https://eclipse-csi.github.io/advisoryhub/
repo_url: https://github.com/eclipse-csi/advisoryhub
repo_name: eclipse-csi/advisoryhub

docs_dir: docs

validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn
  anchors: warn

theme:
  name: material
  palette:
    # Light/dark toggle, following the OS preference on first visit.
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.indexes
    - navigation.top
    - toc.follow
    - search.highlight
    - content.code.copy

extra:
  version:
    provider: mike # Material renders the version selector from ../versions.json
    default: latest

# Vendored CSS styling the OAD-rendered API page (essentials-openapi HTML
# output, originally shipped with neoteroi-mkdocs's release), pinned via
# docs/assets/css/neoteroi-mkdocs.VERSION and checked by dev/check_vendored_assets.sh.
extra_css:
  - assets/css/neoteroi-mkdocs.css

plugins:
  - search
  - mike:
      canonical_version: latest

# Renders specification/openapi.yaml on the API page (OAD tag in
# specification/api.md) at build time — static HTML, no JS app. A thin local
# hook calling essentials-openapi directly, replacing the neoteroi-mkdocs
# plugin (which also dragged in httpx/rich); MKDOCS output style = the old
# use_pymdownx: true.
hooks:
  - dev/mkdocs_oad_hook.py

markdown_extensions:
  # Listing extensions replaces MkDocs' defaults — tables/toc stay explicit.
  - admonition
  - attr_list
  - tables
  - toc:
      permalink: true
      # GitHub-compatible heading slugs: pymdownx turns EVERY space into a
      # dash without collapsing, so "Appendix A — Adding…" yields the same
      # `appendix-a--adding…` anchor as GitHub's renderer — the docs' anchor
      # links were authored against GitHub and keep working on both surfaces.
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  # Required by the OAD hook's MKDOCS output style (tabbed schema views).
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.superfences:
      custom_fences:
        # mkdocs-material's native Mermaid pattern (docs/ uses ```mermaid in
        # manual/, operations/README.md, and advisory-lifecycle.md).
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

nav:
  - Home: index.md
  - User manual:
      - manual/README.md
      - Reporter: manual/reporter.md
      - Collaborator & viewer: manual/collaborator-and-viewer.md
      - Security team: manual/security-team.md
      - Administrator: manual/administrator.md
  - Operations:
      - operations/README.md
      - Installation: operations/installation.md
      - Configuration: operations/configuration.md
      - Running in production: operations/running-in-production.md
      - Deploy on Kubernetes: operations/deploy-kubernetes.md
      - Integrations: operations/integrations.md
      - Observability: operations/observability.md
      - Maintenance: operations/maintenance.md
  - Specification:
      - specification/README.md
      - Invariants: specification/invariant.md
      - Architecture: specification/architecture.md
      - Permissions: specification/permissions.md
      - Advisory lifecycle: specification/advisory-lifecycle.md
      - Requirements: specification/requirements.md
      - API: specification/api.md
  - Contributing:
      - contributing/README.md
      - Releasing: contributing/releasing.md