📝 Add a doc page with examples

Author: foosel

.github/workflows/docs.yaml

@@ -0,0 +1,50 @@
+name: Build & publish docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⬇ Checkout
+        uses: actions/checkout@v3
+
+      - name: 🐍 Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: 🐍 Preinstall some build dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements-docs.txt
+
+      - name: 🏗 Build docs
+        run: |
+          mkdocs build
+        env:
+          SITE_URL: https://octoprint.github.io/mkdocs-site-urls/
+
+      - name: ⬆ Upload pages artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./site
+
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    needs: build
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: 🚀 Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.gitignore

@@ -6,3 +6,5 @@ __pycache__
 *.pyc
 *.pyo
 *.pyd
+venv
+site

docs/assets/example.pdf

@@ -0,0 +1,21 @@
+# Example
+
+!!! example
+
+    === "Markdown"
+
+        ```
+        [link to README](site:.)
+
+        ![example image](site:assets/example.png)
+
+        <object data="site:assets/example.pdf"></object>
+        ```
+
+    === "Output"
+
+        [link to README](site:.)
+
+        ![example image](site:assets/example.png)
+
+        <object data="site:assets/example.pdf"></object>

docs/assets/example.png

@@ -0,0 +1,3 @@
+{%
+  include-markdown "../README.md"
+%}

docs/example/index.md

@@ -0,0 +1,46 @@
+site_name: MkDocs Site URLs Plugin
+site_url: !ENV [SITE_URL, "http://127.0.0.1:8000"]
+dev_addr: 127.0.0.1:8000
+repo_name: OctoPrint/mkdocs-site-urls
+repo_url: https://github.com/OctoPrint/mkdocs-site-urls
+
+nav:
+  - README: index.md
+  - Examples: example/index.md
+
+theme:
+  name: material
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+plugins:
+  - include-markdown
+  - search
+  - site-urls:
+      attributes:
+        - src
+        - href
+        - data
+        - data-src
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+
+watch:
+  - docs
+  - mkdocs.yml
+  - README.md

docs/index.md

@@ -0,0 +1,4 @@
+mkdocs>=1.5.0
+mkdocs-material
+mkdocs-include-markdown-plugin
+-e .