diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..b8ae821 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index c7ccdf1..2f9660c 100644 --- a/README.md +++ b/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 %} +``` diff --git a/data/fruits.yml b/data/fruits.yml new file mode 100644 index 0000000..36978f4 --- /dev/null +++ b/data/fruits.yml @@ -0,0 +1,3 @@ +- Apple +- Banana +- Strawberry diff --git a/docs/configuration/index.md b/docs/configuration/index.md new file mode 100644 index 0000000..fb0f5cc --- /dev/null +++ b/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 + ``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a9eefeb --- /dev/null +++ b/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` diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..e78bdf5 --- /dev/null +++ b/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/ diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..035a014 --- /dev/null +++ b/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 diff --git a/mkdocs_data_plugin/plugin.py b/mkdocs_data_plugin/plugin.py index f862d3f..6fdfb5c 100644 --- a/mkdocs_data_plugin/plugin.py +++ b/mkdocs_data_plugin/plugin.py @@ -1,14 +1,15 @@ -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') @@ -16,12 +17,7 @@ class DataPluginConfig(base.Config): 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,7 +28,6 @@ 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) @@ -40,8 +35,9 @@ def on_config(self, config: MkDocsConfig): 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 - diff --git a/pyproject.toml b/pyproject.toml index 260db75..868eb1a 100644 --- a/pyproject.toml +++ b/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]