Skip to content

Commit b6187c6

Browse files
alganetalganet
committed
Initial Import
0 parents  commit b6187c6

32 files changed

Lines changed: 1709 additions & 0 deletions

‎.github/workflows/deploy.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: "3.12"
28+
cache: pip
29+
30+
- name: Install theme + dev deps
31+
run: pip install -e ".[dev]"
32+
33+
- name: Build site
34+
run: mkdocs build --strict
35+
36+
- name: Upload Pages artifact
37+
uses: actions/upload-pages-artifact@v3
38+
with:
39+
path: ./site
40+
41+
deploy:
42+
needs: build
43+
runs-on: ubuntu-latest
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
steps:
48+
- name: Deploy to GitHub Pages
49+
id: deployment
50+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*.egg-info/
5+
*.egg
6+
build/
7+
dist/
8+
.eggs/
9+
.pytest_cache/
10+
11+
# Virtual envs
12+
.venv/
13+
venv/
14+
env/
15+
16+
# MkDocs
17+
site/
18+
site-*/
19+
preview-*.yml
20+
21+
# OS
22+
.DS_Store
23+
Thumbs.db
24+
25+
# Editors
26+
.vscode/
27+
.idea/
28+
*.swp

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) Respect Project Contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# mkdocs-respect
2+
3+
MkDocs theme for the [Respect](https://github.com/Respect) organization.
4+
Minimalist, monochrome, Ubuntu typography.
5+
6+
## License
7+
8+
[MIT](LICENSE)

‎docs/getting-started.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Getting started
2+
3+
This page is a quick tour of the theme. Use the sidebar to navigate between
4+
pages, the table of contents on the right to jump within a page, and `⌘K`
5+
(or `Ctrl+K`) to open search.
6+
7+
## Why this theme
8+
9+
The theme is intentionally minimal. It is designed for Respect projects,
10+
but you can use it as a minimal, clean mkdocs template for any other
11+
purpose.
12+
13+
## Where to go next
14+
15+
Read the [Installation guide](guide/installation.md) to add the theme to
16+
your project. The [Configuration reference](guide/configuration.md) lists
17+
every option supported under the `theme:` key.
18+
19+
## A small example
20+
21+
Here is the kind of link styling you can expect: visit the
22+
[Respect organization on GitHub](https://github.com/Respect) for the full
23+
list of components.

‎docs/guide/configuration.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Configuration
2+
3+
The theme accepts a small number of options under the `theme:` key in your
4+
`mkdocs.yml`.
5+
6+
## Options
7+
8+
| Option | Type | Default | Description |
9+
| ------------- | ------- | ------- | -------------------------------------------------------- |
10+
| `logo` | string | `null` | Path to the logo shown in the site header. |
11+
| `favicon` | string | `null` | Path to the site favicon. |
12+
| `social` | list | (org) | List of `{ icon, link, name }` entries for the footer. |
13+
| `footer_text` | string | `null` | Custom footer text. Falls back to `copyright` if unset. |
14+
| `language` | string | `en` | Value used for the `<html lang>` attribute. |
15+
16+
When `logo` is unset the theme falls back to its bundled Respect mark.
17+
18+
## Social links
19+
20+
Built-in icons are `github` and `linkedin`. Any other `icon` value falls
21+
back to showing the entry's `name` as text.
22+
23+
```yaml
24+
theme:
25+
name: respect
26+
social:
27+
- icon: github
28+
link: https://github.com/your-org
29+
name: GitHub
30+
- icon: linkedin
31+
link: https://www.linkedin.com/company/your-org
32+
name: LinkedIn
33+
```
34+
35+
!!! note
36+
The theme is monochrome by design. There is no dark-mode option in the
37+
current release.
38+
39+
!!! tip
40+
Use a transparent SVG logo for the cleanest result against the
41+
`#fafafa` page background.
42+
43+
!!! warning
44+
Setting `logo:` to an external URL is not supported. Place the file
45+
inside your `docs/` directory.
46+
47+
!!! danger
48+
Avoid editing the bundled CSS files when you upgrade. Your changes will
49+
be overwritten. Override styles with `extra_css` instead.
50+
51+
## Versioned documentation
52+
53+
The header includes a version selector that activates automatically when
54+
the deployment exposes a `versions.json` at its root. See
55+
[Versioned docs](versioning.md) for the full setup.

‎docs/guide/installation.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Installation
2+
3+
`mkdocs-respect` is published on PyPI. Install it alongside MkDocs:
4+
5+
```bash
6+
pip install mkdocs mkdocs-respect
7+
```
8+
9+
For a project that pins versions, add the package to your requirements
10+
file:
11+
12+
```text
13+
mkdocs>=1.5
14+
mkdocs-respect>=0.1
15+
```
16+
17+
## Use the theme
18+
19+
Set `theme.name` to `respect` in your `mkdocs.yml`:
20+
21+
```yaml
22+
site_name: My Project
23+
theme:
24+
name: respect
25+
logo: assets/logo.svg
26+
plugins:
27+
- search
28+
```
29+
30+
## Verify
31+
32+
Run the strict build to confirm the theme is registered and the docs are
33+
free of broken links:
34+
35+
```bash
36+
mkdocs build --strict
37+
```
38+
39+
Then start the dev server and open <http://127.0.0.1:8000>:
40+
41+
```bash
42+
mkdocs serve
43+
```

‎docs/guide/versioning.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Versioned documentation
2+
3+
The theme ships with a version selector in the header. It is opt-in by
4+
deployment: when the site exposes a `versions.json` at its root the
5+
selector appears, populated, and lets readers switch between versions
6+
while staying on the same page. When `versions.json` is missing the
7+
selector stays hidden and adds nothing to the layout.
8+
9+
The theme does not produce `versions.json` itself. It expects the format
10+
that [`mike`](https://github.com/jimporter/mike) writes when it deploys
11+
multi-version sites to the `gh-pages` branch.
12+
13+
## How the selector works
14+
15+
The browser fetches `versions.json` relative to the deployment root (one
16+
level above the current version directory). Each entry has a `version`,
17+
an optional `title`, and an optional list of `aliases`. The selector
18+
shows the active version's title and any aliases attached to it. Picking
19+
another entry sends the reader to the same page path under that other
20+
version, so deep links survive a version switch.
21+
22+
If the fetch fails (404, network error, malformed JSON) the selector
23+
stays hidden. There is no flash of unstyled content because the partial
24+
renders with `hidden` and is only revealed once the data is in.
25+
26+
## Publishing with mike
27+
28+
Install mike alongside MkDocs:
29+
30+
```bash
31+
pip install mike
32+
```
33+
34+
Deploy a version and tag it as the default `latest`:
35+
36+
```bash
37+
mike deploy --push --update-aliases 1.0 latest
38+
mike set-default --push latest
39+
```
40+
41+
Subsequent releases follow the same pattern. Mike rewrites
42+
`versions.json` on the `gh-pages` branch each time and the selector
43+
reflects the new state on the next page load.
44+
45+
```bash
46+
mike deploy --push --update-aliases 2.0 latest
47+
```
48+
49+
To remove a version:
50+
51+
```bash
52+
mike delete --push 1.0
53+
```
54+
55+
## URL layout
56+
57+
Mike publishes each version into its own subdirectory at the deployment
58+
root. A site published under `https://example.com/myproject/` ends up
59+
shaped like this:
60+
61+
```
62+
myproject/
63+
versions.json
64+
1.0/
65+
index.html
66+
...
67+
2.0/
68+
index.html
69+
...
70+
```
71+
72+
The `versions.json` file uses this shape:
73+
74+
```json
75+
[
76+
{ "version": "2.0", "title": "2.0", "aliases": ["latest"] },
77+
{ "version": "1.0", "title": "1.0", "aliases": [] }
78+
]
79+
```
80+
81+
The selector's "switch to another version" link rewrites the path so
82+
`https://example.com/myproject/2.0/guide/configuration/` becomes
83+
`https://example.com/myproject/1.0/guide/configuration/` when you pick
84+
`1.0`. Pages that only exist in one version land at a 404 and the
85+
bundled 404 page sends the reader back home.
86+
87+
## Testing locally
88+
89+
Mike can serve the multi-version build without pushing:
90+
91+
```bash
92+
mike serve
93+
```
94+
95+
This starts a server that mirrors the `gh-pages` layout, so the selector
96+
behaves the same way it will in production.

‎docs/guide/writing-docs.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Writing docs
2+
3+
The theme styles all the common Markdown constructs. This page demonstrates
4+
how each one renders.
5+
6+
## Headings
7+
8+
Use `#` through `####` to outline a page. Heading anchors appear on hover so
9+
readers can copy direct links.
10+
11+
## Lists
12+
13+
Unordered:
14+
15+
- First item
16+
- Second item
17+
- Third item with a [link](https://github.com/Respect)
18+
19+
Ordered:
20+
21+
1. Run the install command.
22+
2. Configure your `mkdocs.yml`.
23+
3. Run `mkdocs serve`.
24+
25+
Task list:
26+
27+
- [x] Install MkDocs
28+
- [x] Install the Respect theme
29+
- [ ] Write your first page
30+
31+
Nested:
32+
33+
- Components
34+
- Validation
35+
- Assertion
36+
- Stringifier
37+
- Tools
38+
- StringFormatter
39+
40+
## Blockquotes
41+
42+
> Independent, easy to use software components.
43+
44+
## Inline elements
45+
46+
You can mark `inline code`, **bold**, *italic*, and ~~strikethrough~~ text.
47+
Keyboard shortcuts use `<kbd>` like <kbd>⌘</kbd> + <kbd>K</kbd> to open
48+
search.
49+
50+
## Horizontal rules
51+
52+
---
53+
54+
Use `---` to break a long page into clear sections.

0 commit comments

Comments
 (0)