Merge pull request #13 from docsforadobe/change/common-config

Update repo to use common org-wide components

Author: zlovatt

.github/workflows/ci.yml

@@ -22,6 +22,10 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
+
+      - name: Install Python dependencies
+        uses: py-actions/py-dependency-install@v4
+
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
 
       - uses: actions/cache@v4
@@ -30,11 +34,5 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: >
-          pip install
-          markdown_grid_tables
-          mkdocs-exclude-search
-          mkdocs-git-revision-date-localized-plugin
-          mkdocs-material
-          mkdocs-print-site-plugin
+
       - run: mkdocs gh-deploy --force

docs/_global/.gitignore

@@ -0,0 +1,7 @@
+*.sublime-project
+*.sublime-workspace
+.DS_Store
+.vscode/
+__pycache__/
+site/
+venv/

docs/_global/global-syntax-highlight.css renamed to docs/_global/css/global-syntax-highlight.css

@@ -0,0 +1,101 @@
+# Handles merging mkdocs config in a way the native inheritance feature doesn't quite cover
+#
+# This relies on a key in "extra.overrides"
+# Valid keys are `custom_dir: str` and `hooks: [-path/to.py, -path/to.py]`, e.g.
+#
+# ```yml
+# extra:
+#     overrides:
+#         custom_dir: overrides
+#         extra_css:
+#             - docs/_global/css/global.css
+#             - docs/_global/css/global-syntax-highlight.css
+#         extra_javascript:
+#             - docs/_global/js/global.js
+#         hooks:
+#             - hooks/local_override.py
+#             - hooks/local_override2.py
+#         theme_features:
+#             - theme.feature1
+#             - theme.feature2
+# ```
+
+import os
+
+import mkdocs
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.config.config_options import (Hooks, ListOfItems, File, FilesystemObject)
+from mkdocs.structure.files import (Files, File as FileStructure)
+
+# Load any local files into mkdocs
+def append_local_files(files: Files, config: MkDocsConfig, local_files: list):
+    for local_file_path in local_files:
+        local_file = FileStructure(
+            path= local_file_path,
+            src_dir=config["docs_dir"] + "/../",
+            dest_dir=config["site_dir"],
+            use_directory_urls=False,
+        )
+
+        files.append(local_file)
+
+# Load any override theme features
+def merge_local_theme_features(config: MkDocsConfig, theme_features: list):
+    for local_feature in theme_features:
+        config.theme["features"].append(local_feature)
+
+# Add additional theme_override folder
+def merge_local_theme_override(config: MkDocsConfig, custom_dir: str):
+    try:
+        local_override_path = FilesystemObject(exists=True).validate(custom_dir)
+    except Exception as e:
+        raise e
+
+    config.theme.dirs.insert(1, local_override_path)
+
+# Load any override hooks
+def merge_local_hooks(config: MkDocsConfig, hooks: list):
+    try:
+        paths = ListOfItems(File(exists=True)).validate(hooks)
+    except Exception as e:
+        raise e
+
+    for name, path in zip(hooks, paths):
+        config.plugins[name] = Hooks._load_hook(mkdocs, name, path)
+
+def on_files(files: Files, config: MkDocsConfig):
+    if "overrides" in config.extra:
+        extra_overrides = config.extra["overrides"]
+
+        if "extra_css" in extra_overrides:
+            extra_css = extra_overrides["extra_css"]
+            append_local_files(files, config, extra_css)
+
+        if "extra_javascript" in extra_overrides:
+            extra_javascript = extra_overrides["extra_javascript"]
+            append_local_files(files, config, extra_javascript)
+
+
+def on_config(config: MkDocsConfig):
+    if "overrides" in config.extra:
+        extra_overrides = config.extra["overrides"]
+
+        if "hooks" in extra_overrides:
+            hooks = extra_overrides["hooks"]
+            merge_local_hooks(config, hooks)
+
+        if "custom_dir" in extra_overrides:
+            custom_dir = extra_overrides["custom_dir"]
+            merge_local_theme_override(config, custom_dir)
+
+        if "extra_css" in extra_overrides:
+            extra_css = extra_overrides["extra_css"]
+            config.extra_css.extend(extra_css)
+
+        if "extra_javascript" in extra_overrides:
+            extra_javascript = extra_overrides["extra_javascript"]
+            config.extra_javascript.extend(extra_javascript)
+
+        if "theme_features" in extra_overrides:
+            theme_features = extra_overrides["theme_features"]
+            merge_local_theme_features(config, theme_features)

docs/_global/global.css renamed to docs/_global/css/global.css

@@ -0,0 +1,71 @@
+# Shared config for all repos
+copyright: All content is copyright Adobe Systems Incorporated.
+
+extra:
+    homepage: https://docsforadobe.dev
+
+    # Using overrides here as we can't inherit "extra_css"
+    overrides:
+        extra_css:
+            - docs/_global/css/global.css
+            - docs/_global/css/global-syntax-highlight.css
+        extra_javascript:
+            - docs/_global/js/global.js
+
+hooks:
+    - docs/_global/hooks/merge_inherited_config.py
+
+markdown_extensions:
+    admonition: {}
+    markdown_grid_tables: {}
+    md_in_html: {}
+    pymdownx.details: {}
+    pymdownx.superfences: {}
+    pymdownx.tabbed:
+        alternate_style: true
+    pymdownx.tasklist:
+        custom_checkbox: true
+    toc:
+        title: Page Contents
+        permalink: true
+        toc_depth: 3
+
+plugins:
+    git-revision-date-localized: {}
+    search:
+        separator: '[\s\-,\.:!=\[\]()"/]+'
+
+    # Note: print-site must be last!
+    print-site:
+        add_cover_page: true
+        add_print_site_banner: true
+        cover_page_template: "docs/_global/overrides/templates/print_site_cover_page.tpl"
+        print_page_title: "Offline Docs"
+        print_site_banner_template: "docs/_global/overrides/templates/print_site_banner.tpl"
+
+theme:
+    name: material
+    custom_dir: docs/_global/overrides
+    features:
+        - announce.dismiss
+        - content.action.edit
+        - content.action.view
+        - search.highlight
+        - search.suggest
+        - toc.follow
+    palette:
+        # Palette toggle for dark mode
+        - media: "(prefers-color-scheme: dark)"
+          primary: black
+          scheme: slate
+          toggle:
+              icon: material/brightness-4
+              name: Switch to light mode
+
+        # Palette toggle for light mode
+        - media: "(prefers-color-scheme: light)"
+          primary: white
+          scheme: default
+          toggle:
+              icon: material/brightness-7
+              name: Switch to dark mode

docs/_global/hooks/merge_inherited_config.py

@@ -1,7 +1,7 @@
 {% extends "base.html" %}
 
 {% block announce %}
-  Welcome to the new scripting guide!
+  Welcome to the new docsforadobe guide!
 
   This is a work in progress.
 

docs/_global/js/global.js

@@ -0,0 +1,7 @@
+# docsforadobe.dev MkDocs Config
+
+This repo holds the common components shared between this org's hosted MkDocs documentation projects.
+
+The idea is that this repo will be kept up-to-date with global config, and each child repo will use a provided script to download the latest commit from this repo, and have its "local" MkDocs config point to the downloaded files from this repo.
+
+In all cases, each child repo will be able to *override* config items here as needed.

docs/_global/mkdocs.yml

@@ -0,0 +1,5 @@
+markdown_grid_tables
+mkdocs
+mkdocs-git-revision-date-localized-plugin
+mkdocs-material
+mkdocs-print-site-plugin