Skip to content
Login Changemaker Archive. Learn more

# Building the Site with MkDocs Material

Welcome! This guide will help you get started building and customizing your site using 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:

    ./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:

       cd mkdocs

3. Build the site:
   Type:

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

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 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 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:

      claude

- You can also try local AI tools like Ollama 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.
- 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

## 📚 More Resources

- MkDocs User Guide
- Material for MkDocs Features
- BNKops MKdocs Configuration & Customization

Happy building!