feat: custom stylesheets

fix #1081

Author: alandefreitas

.github/workflows/ci.yml

@@ -1027,6 +1027,7 @@ jobs:
                 root="$(pwd)/demos/$project/$variant"
                 src="$root/adoc"
                 dst="$root/adoc-asciidoc"
+                stylesheet="$(pwd)/share/mrdocs/addons/generator/common/layouts/style.css"
           
                 # Create the top-level output dir
                 mkdir -p "$dst"
@@ -1037,7 +1038,7 @@ jobs:
                   rel="${f#"$src/"}"                 # path relative to $src
                   outdir="$dst/$(dirname "$rel")"    # mirror subdir inside $dst
                   mkdir -p "$outdir"
-                  asciidoctor -D "$outdir" "$f"
+                  asciidoctor -a stylesheet="${stylesheet}" -D "$outdir" "$f"
                 done
               done
             fi

docs/modules/ROOT/pages/generators.adoc

@@ -111,6 +111,34 @@ The layout template can include other partial templates to render the symbol dat
 
 The Document Object Model (DOM) for each symbol includes all information about the symbol.One advantage of custom templates over post-processing XML files is the ability to access symbols as a graph.If symbol `A` refers to symbol `B`, some properties of symbol `B` are likely to be required in the documentation of `A`.All templates and generators can access a reference to `B` by searching the symbol tree or simply by accessing the elements `A` refers to.All references to other symbols are resolved in the templates.
 
+== Stylesheet Options
+
+The HTML and AsciiDoc generators ship a bundled stylesheet that is inlined by default. You can replace or layer styles with the following options (available in config files and on the CLI):
+
+- `stylesheets`: ordered list of stylesheet paths or URLs. If empty, the bundled CSS is used. Remote URLs require `linkcss: true`.
+- `no-default-styles`: skip the bundled CSS entirely.
+- `linkcss`: emit `<link>` tags instead of inline `<style>` blocks. Local styles are copied by default; remote URLs are only linked.
+- `copycss`: when linking, copy bundled and local styles into the output tree (default `true`). Set to `false` to skip copying.
+- `stylesdir`: directory (relative to the output root) used for linked styles, e.g. `css` results in `css/custom.css`.
+
+Example config:
+
+[source,yaml]
+----
+generator: html
+stylesheets:
+  - custom.css
+linkcss: true
+stylesdir: css
+----
+
+Equivalent CLI flags:
+
+[source,shell]
+----
+mrdocs --generator=html --stylesheets custom.css --linkcss --stylesdir css
+----
+
 [#dom_reference]
 == Document Object Model Reference
 

docs/mrdocs.schema.json

@@ -55,6 +55,16 @@
       "title": "Path to the compilation database",
       "type": "string"
     },
+    "copycss": {
+      "default": true,
+      "description": "When `linkcss` is true, copy bundled and local stylesheet files into the output under `stylesdir`. Remote URLs are not copied. Set to false to skip copying.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Copy local stylesheets when linking",
+      "type": "boolean"
+    },
     "defines": {
       "default": [],
       "description": "Additional defines passed to the compiler when building the source code. These defines are added to the compilation database regardless of the strategy to generate it.",
@@ -331,6 +341,16 @@
       "title": "Standard Library include paths",
       "type": "array"
     },
+    "linkcss": {
+      "default": false,
+      "description": "When set to true, stylesheets are linked with `<link>` tags instead of being inlined. Links use `stylesdir` plus the stylesheet name (e.g. `css/custom.css`). Local styles are copied unless `copycss` is false; remote URLs are linked as-is.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Link stylesheets instead of embedding them",
+      "type": "boolean"
+    },
     "log-level": {
       "default": "info",
       "description": "The reporting level determines the amount of information displayed during the generation of the documentation.",
@@ -372,6 +392,16 @@
       "title": "Generate a multipage documentation",
       "type": "boolean"
     },
+    "no-default-styles": {
+      "default": false,
+      "description": "When set to true, the bundled stylesheet is not applied. Combine with an empty `stylesheets` list to emit no styles at all.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Disable the bundled default stylesheet",
+      "type": "boolean"
+    },
     "output": {
       "default": "<config-dir>/reference-output",
       "description": "Multipage generators expect a directory. Single page generators expect a file or a directory where the file will be created. If the directory does not exist, it will be created.",
@@ -541,6 +571,21 @@
       "title": "C++ Standard Library include paths",
       "type": "array"
     },
+    "stylesdir": {
+      "default": "css",
+      "description": "Directory used to build the href for linked stylesheets when `linkcss` is true. Defaults to `css`. The directory is created under the output root when copying local styles (e.g. `css/mrdocs-default.css`).",
+      "title": "Directory for linked stylesheets",
+      "type": "string"
+    },
+    "stylesheets": {
+      "default": [],
+      "description": "Ordered list of stylesheet names or paths. If empty, the bundled stylesheet is used. Entries can be local paths or remote URLs; remote URLs are only linked when `linkcss` is true. Inline mode embeds local styles; link mode emits `<link>` tags for each entry and copies local files.",
+      "items": {
+        "type": "string"
+      },
+      "title": "Ordered list of stylesheets to apply to HTML output",
+      "type": "array"
+    },
     "system-includes": {
       "default": [],
       "description": "System include paths. These paths are used to add directories to the system include search path. The system include search path is used to search for system headers. The system headers are headers that are provided by the system and are not part of the project. The system headers are used to provide the standard library headers and other system headers. The system headers are not part of the project and are not checked for warnings and errors.",

share/mrdocs/addons/generator/adoc/layouts/wrapper.adoc.hbs

@@ -17,11 +17,29 @@
 {{#if @root.config.multipage }}
 [#{{{symbol.anchor}}}]
 = {{> symbol/qualified-name-title symbol }}
-:relfileprefix: {{{ repeat "../" (count (remove_prefix symbol.url '/') '/') }}}
+{{#if page.relfileprefix}}
+:relfileprefix: {{{ page.relfileprefix }}}
+{{/if}}
 {{else}}
 = Reference
 {{/if}}
 :mrdocs:
 
+{{!--
+    Optional Asciidoctor stylesheet hints.
+    These are ignored by Antora (it owns the UI bundle), but allow users
+    who render the .adoc directly with Asciidoctor to select/link custom CSS.
+--}}
+{{~#if page.stylesheets}}
+{{#each page.stylesheets}}
+:stylesheet: {{path}}
+{{/each}}
+{{#if @root.config.stylesdir}}
+:stylesdir: {{@root.config.stylesdir}}
+{{/if}}
+{{#if @root.config.linkcss}}
+:linkcss:
+{{/if}}
+{{~/if}}
 {{{contents}}}
 {{#>markup/span class="small"}}Created with https://www.mrdocs.com[MrDocs]{{/markup/span}}

share/mrdocs/addons/generator/common/layouts/highlight.css

@@ -0,0 +1,73 @@
+/* highlight.js Lightfair theme (unmodified) */
+pre code.hljs{
+    display:block;
+    overflow-x:auto;
+    padding:1em;
+}
+code.hljs{
+    padding:3px 5px;
+}
+.hljs{
+    color:#444;
+    background:#fff;
+}
+.hljs-name{
+    color:#01a3a3;
+}
+.hljs-meta,
+.hljs-tag{
+    color:#789;
+}
+.hljs-comment{
+    color:#888;
+}
+.hljs-attribute,
+.hljs-doctag,
+.hljs-keyword,
+.hljs-meta .hljs-keyword,
+.hljs-name,
+.hljs-selector-tag{
+    font-weight:700;
+}
+.hljs-deletion,
+.hljs-number,
+.hljs-quote,
+.hljs-selector-class,
+.hljs-selector-id,
+.hljs-string,
+.hljs-template-tag,
+.hljs-type{
+    color:#4286f4;
+}
+.hljs-section,
+.hljs-title{
+    color:#4286f4;
+    font-weight:700;
+}
+.hljs-link,
+.hljs-regexp,
+.hljs-selector-attr,
+.hljs-selector-pseudo,
+.hljs-symbol,
+.hljs-template-variable,
+.hljs-variable{
+    color:#bc6060;
+}
+.hljs-literal{
+    color:#62bcbc;
+}
+.hljs-addition,
+.hljs-built_in,
+.hljs-bullet,
+.hljs-code{
+    color:#25c6c6;
+}
+.hljs-meta .hljs-string{
+    color:#4d99bf;
+}
+.hljs-emphasis{
+    font-style:italic;
+}
+.hljs-strong{
+    font-weight:700;
+}