fireflyframework-php/mkdocs.yml at main · fireflyframework/fireflyframework-php · 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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
site_name: LaraFly — Firefly Framework for PHP
site_description: Spring Boot's cohesion, native to Laravel.
# The published site (GitHub Pages, from the gh-pages branch `mkdocs gh-deploy` writes). site_url is what
# gives every page a canonical link and the search index its absolute paths; without it Material emits
# relative canonicals and a page opened from a search engine can resolve its own links to the wrong host.
site_url: https://fireflyframework.github.io/fireflyframework-php/

# The canonical home of the source, as every packages/*/composer.json already declares it under
# `support.source` / `homepage`, and as the README's CI badge links to. `edit_uri` points at the default
# branch the same files name (`tree/main/...`), which is what makes `content.action.edit` a real link
# rather than a decorative pencil.
repo_url: https://github.com/fireflyframework/fireflyframework-php
repo_name: fireflyframework/fireflyframework-php
edit_uri: edit/main/docs/
copyright: Apache-2.0 © Firefly Software Solutions Inc.
# Internal design docs (specs/plans) live under docs/superpowers/ and must never
# be built into the published site. They are also git-ignored from the repo.
exclude_docs: |
  superpowers/
  assets/README.md
  README.md
theme:
  name: material
  language: en
  logo: assets/larafly-logo.svg
  favicon: assets/larafly-favicon.svg
  icon:
    repo: fontawesome/brands/github
  # The two schemes are the banner's own two halves: slate #0f172a/#1e293b behind an amber #fbbf24 spark.
  # `custom` is Material's documented hook for a palette that is not one of its named colours — the actual
  # values live in docs/assets/stylesheets/larafly.css, read out of docs/assets/larafly-banner.svg apart from
  # the three that file marks as chosen, each with the reason the banner had nothing to give.
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - toc.follow
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
    - content.action.edit

extra_css:
  - assets/stylesheets/larafly.css

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/fireflyframework/fireflyframework-php
      name: LaraFly on GitHub

markdown_extensions:
  - admonition
  - attr_list
  - def_list
  - md_in_html
  - pymdownx.details
  - pymdownx.inlinehilite
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - toc:
      permalink: true
      toc_depth: 3

# Five tabs, because `navigation.tabs` turns exactly the top level of this list into the header row, and
# five is the number of questions a reader arrives with: what is it (Home), how do I use it (Guide), what is
# in it (Modules), what is it called (Reference), how do I work on it (Contributing).
#
# A TAB OPENS ITS SECTION'S FIRST PAGE — that is the entire mechanism, and it is worth writing down because
# the obvious guess is wrong. Material's `partials/tabs-item.html` links a section's tab to
# `children | first`, descending while that first child is itself a section; nothing else takes part. So
# `- Overview: modules.md` at the top of Modules is what makes that tab land on the landing page rather than
# on Error Handling, and deleting or reordering that one entry silently moves the tab.
#
# Material's `navigation.indexes` is a DIFFERENT feature — it binds a page to the section HEADING in the
# sidebar — and it is deliberately not enabled, because it would do nothing here: it fires only for a page
# MkDocs calls an index (`Page.is_index`, true only for `index.md` or `README.md`), and this landing page is
# `docs/modules.md` on purpose, so that tests/ModuleDocumentationTest.php's glob over `docs/modules/*.md`
# never sees it and never demands a README-table row for it. Listing the feature anyway was measured: with
# `- navigation.indexes` added, `mkdocs build --strict` emits byte-identical HTML apart from the features
# array echoed into the page's own JS config. tests/SiteNavigationTest.php holds both halves — where each
# tab lands, and the rule that `navigation.indexes` may be listed only once a section really has an index
# page.
#
# Every `modules/<name>.md` string below is load-bearing: tests/ModuleDocumentationTest.php greps this file
# for every guide its `docs/modules/*.md` glob turns up and fails if one is missing, so a guide dropped from
# the navigation is red, not invisible. How many that is is deliberately not written down here — a count in a
# comment nobody runs is exactly the rot this release is repairing, and the counts the *pages* quote are
# pinned against the tree by tests/SiteNavigationTest.php instead.
nav:
  - Home: index.md
  - Guide:
      - Installation: installation.md
      - Getting Started: getting-started.md
      - Tutorial: tutorial.md
      - Tutorial (Español): tutorial.es.md
      - Architecture: architecture.md
      - Laravel Comparison: laravel-comparison.md
  - Modules:
      - Overview: modules.md
      - Foundation:
          - Error Handling: modules/error-handling.md
          - Dependency Injection: modules/dependency-injection.md
          - Configuration: modules/configuration.md
          - Application Context: modules/context.md
          - Auto-Configuration: modules/starters.md
          - Validation: modules/validation.md
      - Web & API:
          - Web Layer: modules/web.md
          - Web Filters: modules/web-filters.md
          - OpenAPI: modules/openapi.md
      - Resilience & Scheduling:
          - Resilience: modules/resilience.md
          - Scheduling: modules/scheduling.md
      - Data & Domain:
          - Domain (DDD): modules/domain.md
          - Data & Repositories: modules/data.md
          - Relational Data: modules/data-relational.md
          - Transactions: modules/transactional.md
      - Eventing & Messaging:
          - Event-Driven Architecture: modules/eda.md
          - EDA Brokers: modules/eda-brokers.md
          - Messaging: modules/messaging.md
      - CQRS:
          - CQRS (Command/Query): modules/cqrs.md
      - Security:
          - Security: modules/security.md
          - OAuth2 Client: modules/security-oauth2-client.md
          - OAuth2 Authorization Server: modules/security-oauth2-server.md
      - Operations:
          - Actuator: modules/actuator.md
          - Observability: modules/observability.md
          - Tracing: modules/tracing.md
          - Logging: modules/logging.md
          - Admin Dashboard: modules/admin.md
          - Bean Graph: modules/bean-graph.md
          - Data Browser: modules/data-browser.md
      - Testing:
          - Testing: modules/testing.md
          - Integration Testing: modules/integration-testing.md
      - Tooling:
          - Installer: modules/installer.md
  - Reference:
      - CLI Reference: cli.md
      - Versioning: versioning.md
  - Contributing:
      - Contributing: contributing.md
      - Publishing: publishing.md