added documentation

.github/workflows/deploy-docs.yml

@@ -0,0 +1,26 @@
+name: deploy
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          cache: 'pip'
+      - name: Install Python dependencies
+        run: python -m pip install --upgrade hatch
+      - name: Build and deploy
+        run: hatch -e doc run mkdocs gh-deploy --force

README.md

@@ -1,5 +1,5 @@
 # mkdocs-data-plugin
-MkDocs plugin that allows to read data from markup files
+MkDocs plugin that allows to read data from external markup files.
 
 Currently supported formats:
 
@@ -23,3 +23,30 @@ Activate the plugin in your `mkdocs.yml`:
 plugins:
   - data
 ```
+
+## Overview
+When using this plugin, you can define data in YAML or JSON files
+in a separate directory and reference it in your Markdown files.
+
+```txt
+root/
+├── docs/
+│   └── ...
+├── data/
+│   └── fruits.yml
+└── mkdocs.yml
+```
+
+```yaml title="fruits.yml"
+- Apple
+- Banana
+- Strawberry
+```
+
+Files in this directory can be referenced in your Markdown files using the `data` variable.
+
+```markdown
+{% for fruit in data.fruits -%}
+- {{ fruit }}
+{% endfor %}
+```

data/fruits.yml

@@ -0,0 +1,3 @@
+- Apple
+- Banana
+- Strawberry

docs/configuration/index.md

@@ -0,0 +1,21 @@
+# Configuration
+
+This plugin provides the following configuration options.
+
+## Data Directory
+The `data_dir` option specifies the directory where data files are stored. By default, this is set to `data`.
+
+```yaml
+plugins:
+  - data:
+      data_dir: data
+```
+
+!!! tip
+    It is recommended to configure the `watch` option in the `mkdocs.yml` file
+    to automatically reload the site when data files are modified.
+
+    ```yaml
+    watch:
+      - data
+    ```

docs/index.md

@@ -0,0 +1,47 @@
+---
+title: Home
+---
+# MkDocs Data Plugin
+
+__MkDocs Data Plugin__ is a plugin for [MkDocs](https://www.mkdocs.org/) that allows
+externalizing data from your Markdown files into separate files.
+
+## Overview
+When using this plugin, you can define data in YAML or JSON files
+in a separate directory and reference it in your Markdown files.
+
+```txt
+root/
+├── docs/
+│   └── ...
+├── data/
+│   └── fruits.yml
+└── mkdocs.yml
+```
+
+```yaml title="fruits.yml"
+- Apple
+- Banana
+- Strawberry
+```
+
+Files in this directory can be referenced in your Markdown files using the `data` variable.
+
+```markdown
+{% raw %}
+{% for fruit in data.fruits -%}
+- {{ fruit }}
+{% endfor %}
+{% endraw %}
+```
+/// html | div.result
+{% for fruit in data.fruits -%}
+- {{ fruit }}
+{% endfor %}
+///
+
+## Supported Formats
+The plugin supports the following file formats:
+
+- YAML: `.yml`, `.yaml`
+- JSON: `.json`

docs/installation.md

@@ -0,0 +1,22 @@
+# Installation
+This plugin can be installed via `pip`:
+
+```bash
+pip install mkdocs-data-plugin
+```
+
+## Configuration
+To use the plugin, add the following lines to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - macros
+  - data
+```
+
+## Requirements
+Aside from Python and MkDocs, the plugin has the following dependencies:
+
+- [`mkdocs-macros-plugin`][macros-plugin]: Needed to provide the `data` variable in pages.
+
+    [macros-plugin]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/

mkdocs.yml

@@ -0,0 +1,119 @@
+site_name: "MkDocs Data Plugin Documentation"
+site_author: "Joan Puigcerver Ibáñez"
+site_url: https://joapuiib.github.io/mkdocs-data-plugin/
+repo_name: joapuiib/mkdocs-data-plugin
+repo_url: https://github.com/joapuiib/mkdocs-data-plugin
+
+watch:
+  - data
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/joapuiib
+      name: joapuiib @ GitHub
+
+exclude_docs: |
+  _*
+
+theme:
+  name: material
+  icon:
+    logo: material/file-send-outline
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/link
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      primary: deep purple
+      accent: deep purple
+      scheme: default 
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      primary: deep purple
+      accent: deep purple
+      scheme: slate
+      toggle:
+        icon: material/toggle-switch-off
+        name: Switch to system preference
+
+  features:
+    - announce.dismiss
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - navigation.top
+    - navigation.footer
+    - navigation.indexes
+    - navigation.instant
+    - navigation.tabs
+    - navigation.top
+    - toc.follow
+    - search.share
+    - search.suggest
+
+plugins:
+  - search
+  - alias:
+      use_anchor_titles: true
+  - data
+  - macros
+  - social:
+      enabled: !ENV [CI, false]
+  - tags
+  - git-revision-date-localized
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - sane_lists
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.blocks.html
+  - pymdownx.blocks.caption
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.fancylists:
+      inject_class: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink
+  - pymdownx.saneheaders
+  - pymdownx.snippets
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - toc:
+      permalink: true
+
+nav:
+  - Home:
+    - index.md
+    - installation.md
+  - Configuration:
+    - configuration/index.md

mkdocs_data_plugin/plugin.py

@@ -1,27 +1,23 @@
-import os
-import yaml
 import json
+import os
 
-
+import yaml
+from mkdocs.config import base
+from mkdocs.config import config_options as c
 from mkdocs.config.defaults import MkDocsConfig
-from mkdocs.config import base, config_options as c
 from mkdocs.plugins import BasePlugin, get_plugin_logger
 
 log = get_plugin_logger(__name__)
 
+
 class DataPluginConfig(base.Config):
     data_dir = c.Type(str, default='data')
 
 
 class DataPlugin(BasePlugin[DataPluginConfig]):
     def __init__(self):
         self.data = {}
-        self.processors = {
-            '.yml': yaml.safe_load,
-            '.yaml': yaml.safe_load,
-            '.json': json.load
-        }
-
+        self.processors = {'.yml': yaml.safe_load, '.yaml': yaml.safe_load, '.json': json.load}
 
     def set_data(self, keys, value):
         """
@@ -32,16 +28,16 @@ def set_data(self, keys, value):
             data = data.setdefault(key, {})
         data[keys[-1]] = value
 
-
     def on_config(self, config: MkDocsConfig):
         self.load_data(self.config.data_dir)
 
         macros_plugin = config.plugins.get('macros')
         if macros_plugin:
             macros_plugin.register_variables({'data': self.data})
         else:
-            log.warning("The macros plugin is not installed. The `data` variable won't be available in pages.")
-
+            log.warning(
+                "The macros plugin is not installed. The `data` variable won't be available in pages."
+            )
 
     def load_data(self, path: str):
         """
@@ -61,7 +57,6 @@ def load_data(self, path: str):
                 filename, _ = os.path.splitext(file)
                 self.set_data(keys + [filename], value)
 
-
     def load_file(self, path: str):
         """
         Load a file and return its content.
@@ -70,9 +65,6 @@ def load_file(self, path: str):
         with open(path, 'r') as file:
             return self.processors[extension](file)
 
-
-
     def on_page_context(self, context, page, config, nav):
         context['data'] = self.data
         return context
-

pyproject.toml

@@ -63,7 +63,9 @@ type = ["default"]
 
 [tool.hatch.envs.doc]
 dependencies = [
-    "mkdocs-material>=9.2.5"
+    "mkdocs-material~=9.5",
+    "mkdocs-alias-plugin~=0.8",
+    "mkdocs-git-revision-date-localized-plugin~=1.2",
 ]
 
 [tool.hatch.envs.doc.scripts]
@@ -81,13 +83,13 @@ dependencies = [
 
 [tool.hatch.envs.style.scripts]
 check = [
-    "isort --check-only --diff mkdocs_static_i18n",
-    "black -q --check --diff mkdocs_static_i18n",
-    "ruff check mkdocs_static_i18n",
+    "isort --check-only --diff mkdocs_data_plugin",
+    "black -q --check --diff mkdocs_data_plugin",
+    "ruff check mkdocs_data_plugin",
 ]
 format = [
-    "isort -q mkdocs_static_i18n",
-    "black -q mkdocs_static_i18n",
+    "isort -q mkdocs_data_plugin",
+    "black -q mkdocs_data_plugin",
 ]
 
 [tool.black]