From 3a913ef698830cb4cacbae7c7eed47aa9c08ad3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Fri, 28 Jul 2023 15:36:21 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=89=20Initial=20commit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .editorconfig | 16 +++++++++ .github/workflows/build.yml | 66 ++++++++++++++++++++++++++++++++++++ .gitignore | 8 +++++ .pre-commit-config.yaml | 30 ++++++++++++++++ LICENSE | 21 ++++++++++++ README.md | 38 +++++++++++++++++++++ mkdocs_site_urls/__init__.py | 31 +++++++++++++++++ pyproject.toml | 6 ++++ setup.cfg | 20 +++++++++++ setup.py | 22 ++++++++++++ 10 files changed, 258 insertions(+) create mode 100644 .editorconfig create mode 100644 .github/workflows/build.yml create mode 100644 .gitignore create mode 100644 .pre-commit-config.yaml create mode 100644 LICENSE create mode 100644 README.md create mode 100644 mkdocs_site_urls/__init__.py create mode 100644 pyproject.toml create mode 100644 setup.cfg create mode 100644 setup.py diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..ba2392e --- /dev/null +++ b/.editorconfig @@ -0,0 +1,16 @@ +# This file is for unifying the coding style for different editors and IDEs +# editorconfig.org + +root = true + +[*] +indent_size = 4 +end_of_line = lf +charset = utf-8 +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +max_line_length = 90 + +[*.{yaml,yml}] +indent_size = 2 diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..a824b5e --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,66 @@ +name: Build +on: + push: + pull_request: + release: + types: [published] + workflow_dispatch: + +jobs: + build: + name: ๐Ÿ”จ Build distribution + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: ๐Ÿ— Set up Python 3.7 + uses: actions/setup-python@v4 + with: + python-version: "3.7" + - name: ๐Ÿ— Install build dependencies + run: | + python -m pip install wheel --user + - name: ๐Ÿ”จ Build a binary wheel and a source tarball + run: | + python setup.py sdist bdist_wheel + - name: โฌ† Upload build result + uses: actions/upload-artifact@v3 + with: + name: dist + path: dist + + pre-commit: + name: ๐Ÿงน Pre-commit + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: ๐Ÿ— Set up Python 3.11 + uses: actions/setup-python@v4 + with: + python-version: "3.11" + - name: ๐Ÿ— Set up dev dependencies + run: | + pip install pre-commit + - name: ๐Ÿš€ Run pre-commit + run: | + pre-commit run --all-files --show-diff-on-failure + + publish-on-pypi: + name: ๐Ÿ“ฆ Publish tagged releases to PyPI + if: github.event_name == 'release' && github.repository == 'OctoPrint/mkdocs-site-urls' + needs: + - build + - pre-commit + runs-on: ubuntu-latest + environment: release + permissions: + id-token: write + steps: + - name: โฌ‡ Download build result + uses: actions/download-artifact@v3 + with: + name: dist + path: dist + - name: ๐Ÿ“ฆ Publish to index + uses: pypa/gh-action-pypi-publish@release/v1 + with: + password: ${{ secrets.pypi_token }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f141ad3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +build +dist +*.egg-info +*.egg +__pycache__ +*.pyc +*.pyo +*.pyd diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..535757a --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,30 @@ +default_language_version: + python: python3.11 +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: end-of-file-fixer + - id: trailing-whitespace + - id: check-case-conflict + - id: check-merge-conflict + - id: fix-encoding-pragma + args: ["--remove"] + - repo: https://github.com/asottile/pyupgrade + rev: v3.9.0 + hooks: + - id: pyupgrade + args: ["--py37-plus"] + - repo: https://github.com/pre-commit/mirrors-isort + rev: v5.10.1 + hooks: + - id: isort + - repo: https://github.com/psf/black + rev: 23.7.0 + hooks: + - id: black + - repo: https://github.com/pycqa/flake8 + rev: 6.0.0 + hooks: + - id: flake8 + args: [--config=setup.cfg] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..730706e --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 Gina HรคuรŸge + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ff88d69 --- /dev/null +++ b/README.md @@ -0,0 +1,38 @@ +# MkDocs Site URLs + +A MkDocs plugin that adds support for site-relative `site:` URLs. + +Example: + +| URL | site_url | resulting URL | +| --- | -------- | ------------- | +| `site:images/foo.png` | `https://example.com/` | `/images/foo.png` | +| `site:images/foo.png` | `https://example.com/bar/` | `/bar/images/foo.png` | + +## Usage + +1. Install the plugin from PyPI + ```bash + pip install mkdocs-site-urls + ``` +2. Add the `site-urls` plugin to your `mkdocs.yml` plugins section: + ```yaml + plugins: + - site-urls + ``` + There are no configuration options. +3. Start using site-relative URLs in your Markdown files by prefixing them with `site:`: + ```markdown + [Link to another page](site:another-page/relative/to/the/site/root) + + ![Image](site:images/foo.png) + ``` + +## How it works + +The plugin hooks into the [`on_page_content` event](https://www.mkdocs.org/dev-guide/plugins/#on_page_content) +and replaces all URLs in `href` or `src` attributes in the rendered HTML with the corresponding site-relative URLs. + +## License + +This project is licensed under the MIT license, see the [LICENSE](https://github.com/OctoPrint/mkdocs-site-urls/blob/main/LICENSE) file for details. diff --git a/mkdocs_site_urls/__init__.py b/mkdocs_site_urls/__init__.py new file mode 100644 index 0000000..4a75813 --- /dev/null +++ b/mkdocs_site_urls/__init__.py @@ -0,0 +1,31 @@ +import re +import urllib.parse + +import mkdocs.plugins + +SITE_URLS_REGEX = re.compile(r'(href|src)="site:([^"]+)"', re.IGNORECASE) + +logger = mkdocs.plugins.get_plugin_logger(__name__) + + +class SiteUrlsPlugin(mkdocs.plugins.BasePlugin): + @mkdocs.plugins.event_priority(50) + def on_page_content(self, html, page, config, files): + site_url = config["site_url"] + path = urllib.parse.urlparse(site_url).path + + if not path: + path = "/" + if not path.endswith("/"): + path += "/" + + def _replace(match): + param = match.group(1) + url = match.group(2) + if url.startswith("/"): + url = url[1:] + + logger.info(f"Replacing site:{match.group(2)} with {path}{url}...") + return f'{param}="{path}{url}"' + + return SITE_URLS_REGEX.sub(_replace, html) diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..1989dfe --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,6 @@ +[build-system] +requires = ["setuptools>=40.8.0", "wheel"] +build-backend = "setuptools.build_meta" + +[tool.black] +line-length = 90 diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..1d392b8 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,20 @@ +[metadata] +license_file = LICENSE + +[bdist_wheel] +universal = 1 + +[flake8] +max-line-length = 90 +extend-ignore = E203, E231, E265, E266, E402, E501, E731, B023, B903, B904, B907, B950, W503 +select = B,C,E,F,W,T4,B9 + +[isort] +multi_line_output = 3 +include_trailing_comma = True +force_grid_wrap = 0 +use_parentheses = True +ensure_newline_before_comments = True +line_length = 90 +known_first_party = + mkdocs_site_urls diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..05e3dc1 --- /dev/null +++ b/setup.py @@ -0,0 +1,22 @@ +from setuptools import find_packages, setup + +with open("README.md", encoding="utf-8") as f: + long_description = f.read() + +setup( + name="mkdocs-site-urls", + version="0.1.0", + author="Gina HรคuรŸge", + author_email="gina@octoprint.org", + url="https://github.com/OctoPrint/mkdocs-site-urls", + project_urls={"Source": "https://github.com/OctoPrint/mkdocs-site-urls"}, + keywords=["mkdocs", "plugin"], + packages=find_packages(), + license="MIT", + description="A MkDocs plugin that adds support for site-relative URLs", + long_description=long_description, + long_description_content_type="text/markdown", + include_package_data=True, + python_requires=">=3.7", + entry_points={"mkdocs.plugins": ["site-urls = mkdocs_site_urls:SiteUrlsPlugin"]}, +)