Skip to content

Commit 7df5a86

Browse files
Tygo-van-den-HurkTygo-van-den-Hurk
committed
chore: added a deploy to github pages workflow
This workflow builds the documentation using `mkdocs` and then publishes it onto the github pages site.
1 parent a080aa7 commit 7df5a86

File tree

11 files changed

+241
-27
lines changed

11 files changed

+241
-27
lines changed

‎.github/workflows/push--deploy-github-pages.yaml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Deploy to GitHub Pages
2+
# Updates the GitHub pages website with the changes made in the last push.
3+
# Takes in all markdown files and images of the repository and turns that
4+
# into HTML to present on the GitHub pages website. Used for documentation.
5+
6+
on:
7+
workflow_dispatch:
8+
push:
9+
branches: [main, master, release, development]
10+
paths: [".github/workflows/push--deploy-github-pages.yaml", "mkdocs.yml", "docs/**"]
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: github-pages
19+
cancel-in-progress: false
20+
21+
jobs:
22+
23+
build:
24+
name: Build site
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout repository
28+
uses: actions/[email protected]
29+
- name: Setup Pages
30+
uses: actions/[email protected]
31+
- name: Set up Python
32+
uses: actions/setup-python@v4
33+
with: { python-version: '3.x' }
34+
- name: Install pip
35+
run: python -m pip install --upgrade pip
36+
- name: Install MkDocs and dependencies
37+
run: pip install mkdocs mkdocs-shadcn mkdocstrings-python pymdown-extensions
38+
- name: Build site with MkDocs
39+
run: mkdocs --verbose --color build --site-dir ./_site
40+
- name: Upload artifact
41+
uses: actions/[email protected]
42+
with: { path: ./_site }
43+
44+
deploy:
45+
name: Deploy site
46+
environment:
47+
name: github-pages
48+
url: ${{ steps.deployment.outputs.page_url }}
49+
runs-on: ubuntu-latest
50+
needs: build
51+
steps:
52+
- name: Deploy to GitHub Pages
53+
id: deployment
54+
uses: actions/[email protected]

‎docs/basics.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
to get started make a file called `slyde.xml`, and put in the following text:
44

5-
```XML
5+
```xml
66
<presentation title="My First Slyde Presentation">
77
</presentation>
88
```
@@ -11,7 +11,7 @@ Slyde is made out of XML blocks denoted like this `<tag>...</tag>`. They are an
1111

1212
Now in the presentation block you can add slides as you please. Add one and optionally give it a title:
1313

14-
```XML
14+
```xml
1515
<presentation title="My First Slyde Presentation">
1616
<slide title="Why you should use Slyde">
1717
</slide>
@@ -20,7 +20,7 @@ Now in the presentation block you can add slides as you please. Add one and opti
2020

2121
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/>`:
2222

23-
```XML
23+
```xml
2424
<presentation title="My First Slyde Presentation">
2525
<slide title="Why you should use Slyde">
2626
<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
3232

3333
To style text add [markup](./markup.md). For more information about how markup works in Slyde see [the page on markup](./markup.md)
3434

35-
```XML
35+
```xml
3636
<presentation title="My First Slyde Presentation" by="Tygo van den Hurk">
3737
<slide title="Why you should use Slyde">
3838
<point>It is super **fast and easy** to make slides</point>
@@ -48,7 +48,7 @@ This would output the following fully animated presentation:
4848

4949
You can optionally add presentor notes using XML comments `<!-- ... -->`:
5050

51-
```XML
51+
```xml
5252
<presentation title="My First Slyde Presentation" by="Tygo van den Hurk">
5353
<slide title="Why you should use Slyde">
5454
<!-- These are my slide notes in case I forget what to say -->

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
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.
1414

15-
```XML
15+
```xml
1616
<presentation title="My First Slyde Presentation" by="Tygo van den Hurk">
1717
<slide title="Why you should use Slyde">
1818
<!-- These are my slide notes in case I forget what to say -->

‎docs/markup.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,15 +72,15 @@ This markup is rendered automatically in the text of all components. The markup
7272

7373
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:
7474

75-
```XML
75+
```xml
7676
<text markup="plain">
7777
**This text will NOT be bold**
7878
</text>
7979
```
8080

8181
or use a [processing instruction](./processing-instructions.md):
8282

83-
```XML
83+
```xml
8484
<?slyde markup="plain"?>
8585
<text>
8686
**This text will NOT be bold**
@@ -92,7 +92,7 @@ or use a [processing instruction](./processing-instructions.md):
9292

9393
Or you can use an XML CDATA tag:
9494

95-
```XML
95+
```xml
9696
<text><CDATA[[
9797
**This text will NOT be bold**
9898
]]></text>

‎docs/plugins/component.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
To add your own component simply follow this template:
44

5-
```JavaScript
5+
```javascript
66
// Now available as: my-component, MyComponent, ...
77
export default ({ Component }) => Component.register(
88

@@ -24,7 +24,7 @@ There are a couple of requirements for any instance of `Component`. The function
2424

2525
Now that you've added your own `Component` plugin you can simply use it using its's ID as the element name. Like so:
2626

27-
```XML
27+
```xml
2828
<presentation>
2929
<slide>
3030
<my-component />

‎docs/plugins/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Plugin
2+
3+
[Plugins](https://en.wikipedia.org/wiki/Plug-in_(computing)) are extension to slyde' functionality. I try my best to expose as many different points as possible as I want slyde to work for you, however you seem fit. As of now there are the following possible plugin types:
4+
5+
- [Components](./component.md): the elements you can use in your source file that will render to the final output.
6+
- [MarkUp Renderers](./markup-renderer.md): plugins that transform text using [markup](https://en.wikipedia.org/wiki/Markup_language).
7+

‎docs/plugins/markup-renderer.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
To add your own markup renderer simply follow this template:
44

5-
```JavaScript
5+
```javascript
66
// Now available as: my-language, MyLanguage, ...
77
export default ({ MarkupRenderer }) => MarkupRenderer.register(
88

@@ -23,7 +23,7 @@ There are a couple of requirements for any instance of `MarkupRenderer`. The fun
2323

2424
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).
2525

26-
```XML
26+
```xml
2727
<text markup="my-language">
2828
this is rendered using your new MyLanguage renderer
2929
</text>

‎docs/processing-instructions.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Processing instructions are a special way to tell the compiler things. They do n
66

77
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.
88

9-
```XML
9+
```xml
1010
<text>
1111
**This text will be bold**
1212
</text>
@@ -26,6 +26,6 @@ Here follows a list off all possible instructions:
2626

2727
You can change the markup render to `XYZ` using:
2828

29-
```XML
29+
```xml
3030
<?slyde markup="XYZ"?>
3131
```

‎docs/test.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Pages
3+
summary: Metadata configuration
4+
show_datetime: true
5+
---
6+
7+
Like this page, you can define its title (and subtitle) through front-matter configuration.
8+
9+
```yaml
10+
title: Pages # title
11+
summary: Metadata configuration # subtitle
12+
```
13+
14+
You can also define your page title directly with `# Page title` in the markdown content.
15+
16+
## Navigation
17+
18+
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`).
19+
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.
20+
21+
!!! warning "Important"
22+
`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.
23+
24+
In addition, two other attributes may help to configure pages within the sidebar.
25+
26+
```yaml
27+
order: 2
28+
sidebar_title: Navigation title
29+
```
30+
31+
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:
32+
33+
```ini
34+
| a.md ; order not set
35+
| b.md ; order: 42
36+
| c.md ; order: 0
37+
| d.md ; order not set
38+
```
39+
40+
After a first pass we will have
41+
42+
```ini
43+
| a.md ; order: 0
44+
| b.md ; order: 42
45+
| c.md ; order: 0
46+
| d.md ; order: 1
47+
```
48+
49+
So in the sidebar we will get `a.md`, `c.md`, `d.md` and `b.md`.
50+
51+
!!! danger "Caveat"
52+
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`.
53+
54+
## External links
55+
56+
You can add external links (like "API Reference") in the page header. This is done through the `external_links` attribute in the front-matter.
57+
58+
```yaml
59+
external_links:
60+
"API Reference": https://ui.shadcn.com/docs/components
61+
GitHub: https://github.com/asiffer/mkdocs-shadcn
62+
```
63+
64+
## SEO
65+
66+
The following attributes are supported for SEO (`<meta>` attributes in the `<head>`).
67+
68+
```yaml
69+
description: Extra page description
70+
keywords: mkdocs,shadcn
71+
author: asiffer
72+
image: https://raw.githubusercontent.com/asiffer/mkdocs-shadcn/refs/heads/master/.github/assets/logo.svg
73+
```
74+
75+
## Extra
76+
77+
As we may find in [shadcn/ui](https://ui.shadcn.com/docs), we can add a `NEW` tag in the sidebar
78+
(`Alpha` and `Beta` are also available).
79+
80+
```yaml
81+
new: true
82+
# beta: true
83+
# alpha: true
84+
```
85+
86+
The [`show_datetime` theme option](./get_started.md#show_datetime-bool) can be overriden per page
87+
if you want to show/hide the last update date for a specific page.
88+
89+
```yaml
90+
show_datetime: true
91+
```
92+
93+
94+
Finally you an also load per-page CSS and JS files. This is done through the `extra_css` and `extra_javascript` attributes.
95+
96+
```yaml
97+
extra_css:
98+
- css/custom.css
99+
extra_javascript:
100+
- js/custom.js
101+
```
102+
103+
## Example
104+
105+
```yaml
106+
title: Demo page
107+
summary: Example page for mkdocs-shadcn users
108+
new: true
109+
description: Example page for mkdocs-shadcn users
110+
keywords: mkdocs,shadcn,demo
111+
author: asiffer
112+
image: https://raw.githubusercontent.com/asiffer/mkdocs-shadcn/refs/heads/master/.github/assets/logo.svg
113+
order: 5
114+
sidebar_title: Demo
115+
show_datetime: false
116+
external_links:
117+
"API Reference": https://ui.shadcn.com/docs/components
118+
GitHub: "https://github.com/asiffer/mkdocs-shadcn"
119+
extra_css:
120+
- css/custom-style.css
121+
extra_javascript:
122+
- js/custom-script.js
123+
```

‎mkdocs.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
site_name: Slyde
2+
site_author: Tygo van den Hurk
3+
site_url: https://tygo-van-den-hurk.github.io/Slyde/
4+
site_description: Make beautifully animated Slydes and presentations from XML with ease!
5+
6+
repo_url: https://github.com/Tygo-van-den-Hurk/Slyde
7+
8+
theme:
9+
name: shadcn
10+
show_title: true
11+
show_stargazers: false
12+
pygments_style:
13+
light: github-light
14+
dark: github-dark
15+
icon: assets/logo-standalone.svg
16+
favicon: assets/logo-standalone.svg
17+
show_datetime: true
18+
color_mode: auto
19+
20+
plugins:
21+
- search
22+
- mkdocstrings
23+
24+
markdown_extensions:
25+
admonition:
26+
codehilite:
27+
fenced_code:
28+
footnotes:
29+
extra:
30+
pymdownx.blocks.details:
31+
pymdownx.tabbed:
32+
pymdownx.blocks.tab:
33+
combine_header_slug: true
34+
separator: ___
35+
pymdownx.progressbar:
36+
pymdownx.snippets:
37+
pymdownx.arithmatex:
38+
generic: true
39+
shadcn.extensions.echarts.alpha:
40+
shadcn.extensions.codexec:
41+
shadcn.extensions.iconify:
42+
pymdownx.blocks.caption:

0 commit comments

Comments
 (0)
⚡