chore: added a deploy to github pages workflow

Tygo-van-den-Hurk · Tygo-van-den-Hurk · commit a8ab1e511b09 · 2025-12-23T16:20:34.000+01:00
This workflow builds the documentation using `mkdocs` and then publishes it
onto the github pages site.
diff --git a/.github/workflows/push--deploy-github-pages.yaml b/.github/workflows/push--deploy-github-pages.yaml
@@ -0,0 +1,54 @@
+name: Deploy to GitHub Pages
+# Updates the GitHub pages website with the changes made in the last push.
+# Takes in all markdown files and images of the repository and turns that
+# into HTML to present on the GitHub pages website. Used for documentation.
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main, master, release, development]
+    paths: [".github/workflows/push--deploy-github-pages.yaml", "mkdocs.yml", "docs/**"]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6.0.1
+      - name: Setup Pages
+        uses: actions/configure-pages@v5.0.0
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with: { python-version: '3.x' }
+      - name: Install pip
+        run: python -m pip install --upgrade pip
+      - name: Install MkDocs and dependencies
+        run: pip install mkdocs mkdocs-shadcn mkdocstrings-python pymdown-extensions
+      - name: Build site with MkDocs
+        run: mkdocs --verbose --color build --site-dir ./_site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4.0.0
+        with: { path: ./_site }
+
+  deploy:
+    name: Deploy site
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4.0.5
diff --git a/docs/basics.md b/docs/basics.md
@@ -2,7 +2,7 @@
 
 to get started make a file called `slyde.xml`, and put in the following text:
 
-```XML
+```xml
 <presentation title="My First Slyde Presentation">
 </presentation>
 ```
@@ -11,7 +11,7 @@ Slyde is made out of XML blocks denoted like this `<tag>...</tag>`. They are an
 
 Now in the presentation block you can add slides as you please. Add one and optionally give it a title:
 
-```XML
+```xml
 <presentation title="My First Slyde Presentation">
   <slide title="Why you should use Slyde">
   </slide>
@@ -20,7 +20,7 @@ Now in the presentation block you can add slides as you please. Add one and opti
 
 Slide blocks should always be at the 2nd level. To add text to a slide add 3rd level blocks like `<text>...</text>`, `<point>....</point>`, or `<image/>`:
 
-```XML
+```xml
 <presentation title="My First Slyde Presentation">
   <slide title="Why you should use Slyde">
     <point>It is super fast and easy to make slides</point>
@@ -32,7 +32,7 @@ Slide blocks should always be at the 2nd level. To add text to a slide add 3rd l
 
 To style text add [markup](./markup.md). For more information about how markup works in Slyde see [the page on markup](./markup.md)
 
-```XML
+```xml
 <presentation title="My First Slyde Presentation" by="Tygo van den Hurk">
   <slide title="Why you should use Slyde">
     <point>It is super **fast and easy** to make slides</point>
@@ -48,7 +48,7 @@ This would output the following fully animated presentation:
 
 You can optionally add presentor notes using XML comments `<!-- ... -->`:
 
-```XML
+```xml
 <presentation title="My First Slyde Presentation" by="Tygo van den Hurk">
   <slide title="Why you should use Slyde">
     <!-- These are my slide notes in case I forget what to say -->
diff --git a/docs/index.md b/docs/index.md
@@ -12,7 +12,7 @@
 
 Slyde is a program to create professional beautifully animated presentations from XML. It is fast and easy, even for non-technical people. [See the basics](./basics.md) to get started.
 
-```XML
+```xml
 <presentation title="My First Slyde Presentation" by="Tygo van den Hurk">
   <slide title="Why you should use Slyde">
     <!-- These are my slide notes in case I forget what to say -->
diff --git a/docs/markup.md b/docs/markup.md
@@ -72,15 +72,15 @@ This markup is rendered automatically in the text of all components. The markup
 
 You might not want the markup to be processed at all. In that case you have 3 options. You could switch the markup renderer to the `plain` named renderer. This one just returns the input without processing:
 
-```XML
+```xml
 <text markup="plain">
   **This text will NOT be bold**
 </text>
 ```
 
 or use a [processing instruction](./processing-instructions.md):
 
-```XML
+```xml
 <?slyde markup="plain"?>
 <text>
   **This text will NOT be bold**
@@ -92,7 +92,7 @@ or use a [processing instruction](./processing-instructions.md):
 
 Or you can use an XML CDATA tag:
 
-```XML
+```xml
 <text><CDATA[[
   **This text will NOT be bold**
 ]]></text>
diff --git a/docs/plugins/component.md b/docs/plugins/component.md
@@ -2,7 +2,7 @@
 
 To add your own component simply follow this template:
 
-```JavaScript
+```javascript
 // Now available as: my-component, MyComponent, ...
 export default ({ Component }) => Component.register(
   
@@ -24,7 +24,7 @@ There are a couple of requirements for any instance of `Component`. The function
 
 Now that you've added your own `Component` plugin you can simply use it using its's ID as the element name. Like so:
 
-```XML
+```xml
 <presentation>
   <slide>
     <my-component />
diff --git a/docs/plugins/markup-renderer.md b/docs/plugins/markup-renderer.md
@@ -2,7 +2,7 @@
 
 To add your own markup renderer simply follow this template:
 
-```JavaScript
+```javascript
 // Now available as: my-language, MyLanguage, ...
 export default ({ MarkupRenderer }) => MarkupRenderer.register(
   
@@ -23,7 +23,7 @@ There are a couple of requirements for any instance of `MarkupRenderer`. The fun
 
 Now that you've added your own `MarkupRenderer` plugin you can simply render by using it's ID as the value. [See the markup documentation on how to set a renderer](../markup.md).
 
-```XML
+```xml
 <text markup="my-language">
   this is rendered using your new MyLanguage renderer
 </text>
diff --git a/docs/processing-instructions.md b/docs/processing-instructions.md
@@ -6,7 +6,7 @@ Processing instructions are a special way to tell the compiler things. They do n
 
 An example is the processing instructions to change the [markup renderer](markup.md) to something else from here on out for all next elements and their descendants.
 
-```XML
+```xml
 <text>
   **This text will be bold**
 </text>
@@ -26,6 +26,6 @@ Here follows a list off all possible instructions:
 
 You can change the markup render to `XYZ` using:
 
-```XML
+```xml
 <?slyde markup="XYZ"?>
 ```
diff --git a/docs/test.md b/docs/test.md
@@ -0,0 +1,123 @@
+---
+title: Pages
+summary: Metadata configuration
+show_datetime: true
+---
+
+Like this page, you can define its title (and subtitle) through front-matter configuration.
+
+```yaml
+title: Pages # title
+summary: Metadata configuration # subtitle
+```
+
+You can also define your page title directly with `# Page title` in the markdown content.
+
+## Navigation
+
+The navigation follows bare mkdocs. You should just notice that folders will create categories in the sidebar (or in the top bar when `topbar_sections: true`).
+To sort the sections, you can use the common `00_section_title/` hack. The first numbers sort the folders in the filesystem (so the sections). They are removed by the theme at compile time. 
+
+!!! warning "Important"
+    `mkdocs-shadcn` has not been extensively tested with highly nested documentation (`d>2`, i.e. `root / folder / folder`). When subfolders are used, we may recommend to activate the [`topbar_sections`](./get_started.md#topbar_sections-bool) option in the theme configuration. This will display the top level sections in the top bar.
+
+In addition, two other attributes may help to configure pages within the sidebar.
+
+```yaml
+order: 2 
+sidebar_title: Navigation title
+```
+
+The `order` attribute may help to change the rank of the page in the sidebar (without setting the `nav` setting in `mkdocs.yml`). By default, mkdocs ranks pages through alphabetical order. We keep this behavior if `order` is not set. Let us take this example:
+
+```ini
+| a.md ; order not set
+| b.md ; order: 42
+| c.md ; order: 0
+| d.md ; order not set
+```
+
+After a first pass we will have
+
+```ini
+| a.md ; order: 0
+| b.md ; order: 42
+| c.md ; order: 0
+| d.md ; order: 1
+```
+
+So in the sidebar we will get `a.md`, `c.md`, `d.md` and `b.md`.
+
+!!! danger "Caveat"
+    The sidebar order does not change the internal navigation order. It implies that `previous` and `next` pages are unlikely to match a custom order. To prevent that, either use the classical `00_page.md`, `01_page.md`, `02_page.md` ... file pattern in your folder or set the navigation in `mkdocs.yml`.
+
+## External links
+
+You can add external links (like "API Reference") in the page header. This is done through the `external_links` attribute in the front-matter.
+
+```yaml
+external_links:
+  "API Reference": https://ui.shadcn.com/docs/components
+  GitHub: https://github.com/asiffer/mkdocs-shadcn
+```
+
+## SEO
+
+The following attributes are supported for SEO (`<meta>` attributes in the `<head>`).
+
+```yaml
+description: Extra page description
+keywords: mkdocs,shadcn
+author: asiffer
+image: https://raw.githubusercontent.com/asiffer/mkdocs-shadcn/refs/heads/master/.github/assets/logo.svg
+```
+
+## Extra
+
+As we may find in [shadcn/ui](https://ui.shadcn.com/docs), we can add a `NEW` tag in the sidebar 
+(`Alpha` and `Beta` are also available).
+
+```yaml
+new: true
+# beta: true
+# alpha: true
+```
+
+The [`show_datetime` theme option](./get_started.md#show_datetime-bool) can be overriden per page 
+if you want to show/hide the last update date for a specific page.
+
+```yaml
+show_datetime: true
+```
+
+
+Finally you an also load per-page CSS and JS files. This is done through the `extra_css` and `extra_javascript` attributes.
+
+```yaml
+extra_css:
+  - css/custom.css
+extra_javascript:
+  - js/custom.js
+```
+
+## Example
+
+```yaml
+title: Demo page
+summary: Example page for mkdocs-shadcn users
+new: true
+description: Example page for mkdocs-shadcn users
+keywords: mkdocs,shadcn,demo
+author: asiffer
+image: https://raw.githubusercontent.com/asiffer/mkdocs-shadcn/refs/heads/master/.github/assets/logo.svg
+order: 5
+sidebar_title: Demo
+show_datetime: false
+external_links:
+  "API Reference": https://ui.shadcn.com/docs/components
+  GitHub: "https://github.com/asiffer/mkdocs-shadcn"
+extra_css:
+  - css/custom-style.css
+extra_javascript:
+  - js/custom-script.js
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,43 @@
+site_name: Slyde
+site_author: Tygo van den Hurk
+site_url: https://tygo-van-den-hurk.github.io/Slyde/
+site_description: Make beautifully animated Slydes and presentations from XML with ease!
+
+repo_url: https://github.com/Tygo-van-den-Hurk/Slyde
+
+theme: 
+  name: shadcn
+  icon: assets/logo-standalone.svg
+  favicon: assets/logo-standalone.svg
+  show_title: true
+  show_stargazers: false
+  pygments_style:
+    light: github-light
+    dark: github-dark
+  highlightjs: false
+  show_datetime: true
+  color_mode: auto
+
+plugins: 
+  - search
+  - mkdocstrings
+
+markdown_extensions:
+  admonition:
+  codehilite:
+  fenced_code:
+  footnotes:
+  extra:
+  pymdownx.blocks.details:
+  pymdownx.tabbed:
+  pymdownx.blocks.tab:
+    combine_header_slug: true
+    separator: ___
+  pymdownx.progressbar:
+  pymdownx.snippets:
+  pymdownx.arithmatex:
+    generic: true
+  shadcn.extensions.echarts.alpha:
+  shadcn.extensions.codexec:
+  shadcn.extensions.iconify:
+  pymdownx.blocks.caption:
diff --git a/typedoc.json b/typedoc.json
