Skip to content

Commit 80a2224

Browse files
dct0dct0
committed
Setup docs page
1 parent c94050a commit 80a2224

File tree

12 files changed

+422
-1
lines changed

12 files changed

+422
-1
lines changed

‎.github/workflows/publish.yaml

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Workflow for deploying to github
2+
name: Publish docs via GitHub Pages
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- mkdocs-experimental
8+
workflow_dispatch:
9+
10+
jobs:
11+
deploy:
12+
name: Deploy docs
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout main
16+
uses: actions/checkout@v4
17+
18+
- name: Setup Python
19+
uses: actions/setup-python@v5
20+
with:
21+
cache: "pip"
22+
python-version: "3.13"
23+
24+
- name: Install dependencies
25+
run: pip install -r ./requirements.txt
26+
27+
- run: mkdocs build
28+
env:
29+
ENABLE_PDF_EXPORT: 1
30+
31+
- name: Deploy
32+
uses: peaceiris/actions-gh-pages@v4
33+
with:
34+
github_token: ${{ secrets.GITHUB_TOKEN }}
35+
publish_dir: ./site

‎README.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,7 @@
1-
# tech-docs
1+
# tech-docs
2+
3+
## Why?
4+
5+
## Contributing
6+
7+
See the [contributions](./docs/contributions.md) page for more information.

‎docs/.meta.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
ᴴₒᴴₒᴴₒ: true

‎docs/CNAME

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs.codersforcauses.org

‎docs/contributions.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Contributions
2+
3+
Hi! We are happy that you thought of contributing! If you have any suggestions or issues, please raise it [here](https://github.com/codersforcauses/tech-docs/issues). I would be happy if you could provide pull requests, if you know how to do it [here](https://github.com/codersforcauses/tech-docs/pulls).
4+
5+
## Structure
6+
7+
### Folder Structure
8+
9+
The structure of this repo is as follows:
10+
11+
```
12+
├── docs // Folders for documentation
13+
│ ├── CNAME
14+
│ ├── contributions.md
15+
│ ├── deployment_and_automated_site_deployment.md
16+
│ ├── flavoured_markdown.md
17+
│ ├── images // Assets
18+
│ │ └── ...
19+
│ │
20+
│ ├── index.md
21+
│ └── writing_markdown.md
22+
├── LICENSE
23+
├── mkdocs.yml // MkDocs Configuration
24+
├── overrides
25+
│ └── partials
26+
│ └── footer.html
27+
├── README.md
28+
└── requirements.txt
29+
```
30+
31+
## Installation
32+
33+
### Ye olde way
34+
35+
```bash
36+
python -m venv .venv
37+
./.venv/Scripts/activate
38+
pip install -r requirements.txt
39+
mkdocs serve
40+
```
41+
42+
### Docker
43+
44+
```bash
45+
docker compose up
46+
```
47+
48+
## Commands
49+
50+
- `mkdocs new [dir-name]` - Create a new project.
51+
- `mkdocs serve` - Start the live-reloading docs server. Very helpful when you want to take a look at the docs before deploying.
52+
- `mkdocs build` - Build the documentation site.
53+
- `mkdocs -h` - Print help message and exit.
54+
- `mkdocs gh-deploy` - Deploy in github pages
55+
- `pip freeze > requirements.txt` - Generate a requirements.txt file
56+
57+
## Web Documentation Configuration
58+
59+
For full documentation visit:
60+
61+
- [mkdocs.org](https://www.mkdocs.org) for the generic MkDocs
62+
- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) for the different extensions that are installed
63+
- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) for the customisation of the web server documentation.

‎docs/images/cfc_logo_black_full.png

17.8 KB
Loading

‎docs/images/cfc_logo_white_circle.png

31.9 KB
Loading

‎docs/index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Coders for Causes Tech Docs
2+
3+
A place for CFC committee to pass down their knowledge for all things technical.

‎docs/stylesheets/extra.css

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
@import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;700&family=IBM+Plex+Sans:wght@400;700&display=swap");
2+
3+
:root {
4+
--md-text-font: "IBM Plex Sans";
5+
--md-code-font: "IBM Plex Mono";
6+
}
7+
8+
[data-md-color-scheme="cfclight"] {
9+
--md-default-fg-color: #000;
10+
--md-default-fg-color--light: #000;
11+
--md-default-fg-color--lighter: #fff;
12+
--md-default-fg-color--lightest: #fff;
13+
--md-default-bg-color: #fff;
14+
--md-default-bg-color--light: #fff;
15+
--md-default-bg-color--lighter: #fff;
16+
--md-default-bg-color--lightest: #fff;
17+
18+
--md-code-fg-color: #000;
19+
--md-code-bg-color: #fafafa;
20+
--md-code-hl-color: #559999;
21+
--md-code-hl-color--light: #5599991a;
22+
--md-code-hl-number-color: #d52a2a;
23+
--md-code-hl-special-color: #db1457;
24+
--md-code-hl-function-color: #a846b9;
25+
--md-code-hl-constant-color: #6e59d9;
26+
--md-code-hl-keyword-color: #3f6ec6;
27+
--md-code-hl-string-color: #1c7d4d;
28+
--md-code-hl-name-color: var(--md-code-fg-color);
29+
--md-code-hl-operator-color: var(--md-default-fg-color--light);
30+
--md-code-hl-punctuation-color: var(--md-default-fg-color--light);
31+
--md-code-hl-comment-color: var(--md-default-fg-color--light);
32+
--md-code-hl-generic-color: var(--md-default-fg-color--light);
33+
--md-code-hl-variable-color: var(--md-default-fg-color--light);
34+
35+
--md-typeset-color: var(--md-default-fg-color);
36+
--md-typeset-a-color: #488;
37+
--md-typeset-del-color: #f5503d26;
38+
--md-typeset-ins-color: #0bd57026;
39+
--md-typeset-kbd-color: #fafafa;
40+
--md-typeset-kbd-accent-color: #fff;
41+
--md-typeset-kbd-border-color: #b8b8b8;
42+
--md-typeset-mark-color: #ffff0080;
43+
--md-typeset-table-color: #0000001f;
44+
--md-typeset-table-color--light: rgba(0, 0, 0, 0.035);
45+
46+
--md-admonition-fg-color: var(--md-default-fg-color);
47+
--md-admonition-bg-color: var(--md-default-bg-color);
48+
--md-warning-fg-color: #000000de;
49+
--md-warning-bg-color: #ff9;
50+
--md-footer-fg-color: #fff;
51+
--md-footer-fg-color--light: #ffffffb3;
52+
--md-footer-fg-color--lighter: #ffffff73;
53+
--md-footer-bg-color: #000000de;
54+
--md-footer-bg-color--dark: #00000052;
55+
56+
--md-shadow-z1: 0 0.2rem 0.5rem #0000000d, 0 0 0.05rem #0000001a;
57+
--md-shadow-z2: 0 0.2rem 0.5rem #0000001a, 0 0 0.05rem #00000040;
58+
--md-shadow-z3: 0 0.2rem 0.5rem #0003, 0 0 0.05rem #00000059;
59+
60+
--md-primary-fg-color: #000;
61+
--md-primary-fg-color--light: #000;
62+
--md-primary-fg-color--dark: #000;
63+
--md-primary-bg-color: #fff;
64+
--md-primary-bg-color--light: #fff;
65+
--md-accent-fg-color: #488;
66+
--md-accent-fg-color--transparent: #488;
67+
--md-accent-bg-color: #fff;
68+
--md-accent-bg-color--light: #fff;
69+
}
70+
71+
[data-md-color-scheme="cfcdark"] {
72+
--md-default-fg-color: #fff;
73+
--md-default-fg-color--light: #fff;
74+
--md-default-fg-color--lighter: #000;
75+
--md-default-fg-color--lightest: #000;
76+
--md-default-bg-color: #000;
77+
--md-default-bg-color--light: #000;
78+
--md-default-bg-color--lighter: #000;
79+
--md-default-bg-color--lightest: #000;
80+
81+
--md-code-fg-color: #fff;
82+
--md-code-bg-color: #101010;
83+
--md-code-hl-color: #559999;
84+
--md-code-hl-color--light: #5599991a;
85+
--md-code-hl-number-color: #d52a2a;
86+
--md-code-hl-special-color: #db1457;
87+
--md-code-hl-function-color: #a846b9;
88+
--md-code-hl-constant-color: #6e59d9;
89+
--md-code-hl-keyword-color: #4db4d0;
90+
--md-code-hl-string-color: #2eb270;
91+
--md-code-hl-name-color: var(--md-code-fg-color);
92+
--md-code-hl-operator-color: var(--md-default-fg-color--light);
93+
--md-code-hl-punctuation-color: var(--md-default-fg-color--light);
94+
--md-code-hl-comment-color: var(--md-default-fg-color--light);
95+
--md-code-hl-generic-color: var(--md-default-fg-color--light);
96+
--md-code-hl-variable-color: var(--md-default-fg-color--light);
97+
98+
--md-typeset-color: var(--md-default-fg-color);
99+
--md-typeset-a-color: #8ff;
100+
--md-typeset-del-color: #f5503d26;
101+
--md-typeset-ins-color: #0bd57026;
102+
--md-typeset-kbd-color: #fafafa;
103+
--md-typeset-kbd-accent-color: #fff;
104+
--md-typeset-kbd-border-color: #b8b8b8;
105+
--md-typeset-mark-color: #ffff0080;
106+
--md-typeset-table-color: #0000001f;
107+
--md-typeset-table-color--light: rgba(0, 0, 0, 0.035);
108+
109+
--md-admonition-fg-color: var(--md-default-fg-color);
110+
--md-admonition-bg-color: var(--md-default-bg-color);
111+
--md-warning-fg-color: #000000de;
112+
--md-warning-bg-color: #ff9;
113+
114+
--md-footer-fg-color: #fff;
115+
--md-footer-fg-color--light: #fff;
116+
--md-footer-fg-color--lighter: #fff;
117+
--md-footer-bg-color: #000;
118+
--md-footer-bg-color--dark: #000;
119+
--md-shadow-z1: 0 0.2rem 0.5rem #fff, 0 0 0.05rem #fff;
120+
--md-shadow-z2: 0 0.2rem 0.5rem #fff, 0 0 0.05rem #fff;
121+
--md-shadow-z3: 0 0.2rem 0.5rem #fff, 0 0 0.05rem #fff;
122+
123+
--md-primary-fg-color: #000;
124+
--md-primary-fg-color--light: #000;
125+
--md-primary-fg-color--dark: #000;
126+
--md-primary-bg-color: #fff;
127+
--md-primary-bg-color--light: #fff;
128+
--md-accent-fg-color: #4db4d0;
129+
--md-accent-fg-color--transparent: #4db4d0;
130+
--md-accent-bg-color: #000;
131+
--md-accent-bg-color--light: #000;
132+
}

‎mkdocs.yml

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# This configuration can be changed from this https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
2+
# I will be putting comments on certain places where necessary
3+
4+
site_name: Coders for Causes Tech Docs
5+
site_author: Coders for Causes
6+
site_url: https://docs.codersforcauses.org/
7+
repo_url: https://github.com/codersforcauses/tech-docs/
8+
9+
author_website: https://codersforcauses.org/ # remove this if you removed the override/partial
10+
11+
# This uri refers to the github path to edit, change this if you branch is different in name
12+
edit_uri: edit/main/docs/
13+
theme:
14+
name: material
15+
custom_dir: overrides # remove this if you removed the override/partial
16+
palette:
17+
- media: "(prefers-color-scheme: light)" # below here is a palette for light mode
18+
scheme: cfclight
19+
toggle:
20+
icon: material/toggle-switch-off-outline
21+
name: Switch to dark mode
22+
- media: "(prefers-color-scheme: dark)" # below here is a palette for dark mode
23+
scheme: cfcdark
24+
toggle:
25+
icon: material/toggle-switch
26+
name: Switch to light mode
27+
28+
logo: images/cfc_logo_white_circle.png
29+
favicon: images/cfc_logo_white_circle.png
30+
features: # Refer to https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/
31+
- navigation.instant
32+
- navigation.tabs
33+
- toc.integrate
34+
- header.autohide
35+
- content.code.annotate
36+
37+
plugins:
38+
- search
39+
40+
# These are markdown extensions I have included that makes the documentation look nicer
41+
# These extensions are from here https://facelessuser.github.io/pymdown-extensions/
42+
markdown_extensions:
43+
- admonition
44+
- attr_list
45+
- pymdownx.arithmatex:
46+
generic: true
47+
- pymdownx.details
48+
- pymdownx.smartsymbols
49+
- pymdownx.highlight:
50+
use_pygments: true
51+
linenums: true
52+
- pymdownx.tabbed
53+
- footnotes
54+
- pymdownx.critic
55+
- attr_list
56+
- def_list
57+
- pymdownx.tasklist
58+
- pymdownx.inlinehilite
59+
- pymdownx.keys
60+
- pymdownx.mark
61+
- pymdownx.emoji:
62+
emoji_index: !!python/name:materialx.emoji.twemoji
63+
emoji_generator: !!python/name:materialx.emoji.to_svg
64+
- tables
65+
- toc:
66+
permalink: true
67+
toc_depth: 2
68+
- codehilite
69+
- pymdownx.snippets:
70+
base_path: docs
71+
- pymdownx.superfences:
72+
custom_fences:
73+
- name: mermaid
74+
class: mermaid
75+
format: !!python/name:pymdownx.superfences.fence_code_format
76+
77+
extra:
78+
social:
79+
- icon: octicons/globe-16
80+
link: https://codersforcauses.org/
81+
- icon: fontawesome/brands/instagram
82+
link: https://www.instagram.com/cfc_uwa/
83+
- icon: fontawesome/brands/facebook
84+
link: https://www.facebook.com/codersforcauses
85+
- icon: fontawesome/brands/youtube
86+
link: https://www.youtube.com/channel/UCp47I0qUXeGgSK0AtFJSkbQ
87+
- icon: fontawesome/brands/linkedin
88+
link: https://www.linkedin.com/company/coders-for-causes/
89+
- icon: fontawesome/solid/paper-plane
90+
link: mailto:[email protected]
91+
92+
93+
# Add google Analytics when you need it
94+
# Remove this if you dont need it
95+
# https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/
96+
# google_analytics:
97+
# - UA-162451015-2
98+
# - auto
99+
100+
# This is the extra javascript included in the documentation
101+
extra_javascript:
102+
- https://polyfill.io/v3/polyfill.min.js?features=es6
103+
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
104+
- https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
105+
- javascripts/tablesort.js
106+
107+
# If you want to put extra CSS
108+
extra_css:
109+
- stylesheets/extra.css
110+
111+
# This is where you adjust the hierarchy if the documentation
112+
# You can erase this if you want. If you erase this, Mkdocs will alphabetically sort your documentation
113+
nav:
114+
- About:
115+
- Overview: index.md
116+
- Contributions: contributions.md

0 commit comments

Comments
 (0)