108 lines
4.0 KiB
Markdown
108 lines
4.0 KiB
Markdown
# Building the Site with MkDocs Material
|
|
|
|
Welcome! This guide will help you get started building and customizing your site using [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
|
|
|
|
---
|
|
|
|
## Reset Site
|
|
|
|
You can read through all the BNKops cmlite documentation already in your docs folder or you can reset your docs folder to a baseline to start and read more manuals here. To reset docs folder to baseline, run the following:
|
|
|
|
```bash
|
|
./reset-site.sh
|
|
```
|
|
|
|
|
|
## 🚀 How to Build Your Site (Step by Step)
|
|
|
|
1. **Open your Coder instance.**
|
|
For example: coder.yourdomain.com
|
|
2. **Go to the mkdocs folder:**
|
|
In the terminal (for a new terminal press Crtl - Shift - ~), type:
|
|
```sh
|
|
cd mkdocs
|
|
```
|
|
3. **Build the site:**
|
|
Type:
|
|
```sh
|
|
mkdocs build
|
|
```
|
|
This creates the static website from your documents and places them in the `mkdocs/site` directory.
|
|
|
|
**Preview your site locally:**
|
|
Visit [localhost:4000](localhost:4000) for local development or `live.youdomain.com` to see a public live load.
|
|
|
|
- All documentation in the `mkdocs/docs` folder is included automatically.
|
|
- The site uses the beautiful and easy-to-use Material for MkDocs theme.
|
|
|
|
[Material for MkDocs Documentation :material-arrow-right:](https://squidfunk.github.io/mkdocs-material/){ .md-button }
|
|
|
|
!!! note "Build vs Serve"
|
|
Your website is built in stages. Any edits to documents in the mkdocs directory are instantly served and visible at [localhost:4000](localhost:4000) or if in production mode live.yourdomain.com. **The live site is not meant as a public access point and will crash if too many requests are made to it**.
|
|
|
|
Running `mkdocs build` pushes any changes to the `site` directory, which then a ngnix server pushes them to the production server for public access at your root domain (yourdomain.com).
|
|
|
|
You can think of it as serve/live = draft for personal review and build = save/push to production for the public.
|
|
|
|
This combination allows for rapid development of documentation while ensuring your live site does not get updated until your content is ready.
|
|
|
|
---
|
|
|
|
## 🧹 Resetting the Site
|
|
|
|
If you want to start fresh:
|
|
|
|
1. **Delete all folders EXCEPT these folders:**
|
|
- `/blog`
|
|
- `/javascripts`
|
|
- `/hooks`
|
|
- `/assets`
|
|
- `/stylesheets`
|
|
- `/overrides`
|
|
|
|
2. **Reset the landing page:**
|
|
- Open the main `index.md` file and remove everything at the very top (the "front matter").
|
|
- *Or* edit `/overrides/home.html` to change the landing page.
|
|
|
|
3. **Reset the `mkdocs.yml`**
|
|
- Open `mkdocs.yml` and delete the `nav` section entirely.
|
|
- This action will enable mkdocs to build your site navigation based on file names in the root directory.
|
|
|
|
---
|
|
|
|
## 🤖 Using AI to Help Build Your Site
|
|
|
|
- If you have a [claude.ai](https://claude.ai/) subscription, you can use powerful AI in your Coder terminal to write or rewrite pages, including a new `home.html`.
|
|
- All you need to do is open the terminal and type:
|
|
```sh
|
|
claude
|
|
```
|
|
- You can also try local AI tools like [Ollama](https://ollama.com/) for on-demand help.
|
|
|
|
---
|
|
|
|
## 🛠️ First-Time Setup Tips
|
|
|
|
- **Navigation:**
|
|
Open `mkdocs.yml` and remove the `nav` section to start with a blank menu. Add your own pages as you go.
|
|
- **Customize the look:**
|
|
Check out the [Material for MkDocs customization guide](https://squidfunk.github.io/mkdocs-material/setup/changing-the-theme/).
|
|
- **Live preview:**
|
|
Use `mkdocs serve` (see above) to see changes instantly as you edit.
|
|
- **Custom files:**
|
|
Put your own CSS, JavaScript, or HTML in `/assets`, `/stylesheets`, `/javascripts`, or `/overrides`.
|
|
|
|
[Quick Start Guide :material-arrow-right:](https://squidfunk.github.io/mkdocs-material/creating-your-site/){ .md-button }
|
|
|
|
---
|
|
|
|
## 📚 More Resources
|
|
|
|
- [MkDocs User Guide :material-arrow-right:](https://www.mkdocs.org/user-guide/){ .md-button }
|
|
- [Material for MkDocs Features :material-arrow-right:](https://squidfunk.github.io/mkdocs-material/setup/){ .md-button }
|
|
- [BNKops MKdocs Configuration & Customization](../config/mkdocs.md){ .md-button }
|
|
|
|
---
|
|
|
|
Happy building!
|