# 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!