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

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

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