admin/freealberta
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
freealberta/mkdocs/docs/build/site.md

4.0 KiB
Raw Blame History

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 :material-arrow-right:{ .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 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 :material-arrow-right:{ .md-button }

📚 More Resources

Happy building!