mirror of
https://gitlab.waag.org/make/fablab/interns/2025/sam.git
synced 2025-08-04 04:14:56 +00:00
structuring the project and docs about drone code
This commit is contained in:
56
docs/Assignments/week_1_fabacademy/customising_mkdocs.md
Normal file
56
docs/Assignments/week_1_fabacademy/customising_mkdocs.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Customising Mkdocs
|
||||
|
||||
I wanna customise my mkdocs theme. So I can have a dark mode. Because it currently looks like this and having a nice looking documentation page is necessary too!
|
||||
|
||||

|
||||
|
||||
## Issues
|
||||
|
||||
### Attempt 1
|
||||
I tried changing it by referencing extra css but when it builded i looked through the job artifacts and I saw that it didnt pick up on the file
|
||||
|
||||
```yml
|
||||
site_name: Fab Academy docs page - Sam
|
||||
site_url: https://pages.gitlab.io/mkdocs
|
||||
site_dir: public
|
||||
theme:
|
||||
name: ivory
|
||||
extra_css: [extra.css]
|
||||
```
|
||||
```css
|
||||
.footer-note {
|
||||
color:rgb(47, 44, 44) !important
|
||||
}
|
||||
|
||||
.home .version {
|
||||
color:rgb(47, 44, 44) !important
|
||||
}
|
||||
```
|
||||
### Attempt 2
|
||||
After I read the documentation thoroughly i found out that the css file needs to be relative to the `docs` folder and not the `mkdocs.yml`. After that it showed the css and I could finaly customise the theme.
|
||||
|
||||
## Customising Material theme
|
||||
### Palette customisation
|
||||
I decided to switch to material theme because its easier to configure. There are premade color schemes and a lot of extensions that work out of the box.
|
||||
Example changing colors.
|
||||
```yaml
|
||||
theme:
|
||||
palette:
|
||||
primary: indigo
|
||||
accent: teal
|
||||
```
|
||||
Of yourse you could also use the extra.css to style the website even more.
|
||||
### Extensions
|
||||
You can add lot's of extensions. For example code highlighting or a table of contents on the right side of your website.
|
||||
This adds a table of contents. You can find all the extensions [here](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#table-of-contents).
|
||||
```yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: true
|
||||
```
|
||||
|
||||
|
||||
### Links
|
||||
* [markdown extensions](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#table-of-contents)
|
||||
* https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#table-of-contents
|
||||
* [mkdocs extra css](https://www.mkdocs.org/user-guide/customizing-your-theme/)
|
Reference in New Issue
Block a user