Beginner's Guide to Setting Up a MkDocs Site with Publisher Plugin¶

Introduction¶

This guide will walk you through setting up a documentation website using MkDocs with the Publisher plugin. It's designed for beginners with little technical knowledge.

Prerequisites¶

A computer running Ubuntu or a similar Linux distribution
Basic familiarity with using the terminal

Step 1: Setting Up Your Environment¶

Open your terminal.
Create a new folder for your project:
```
mkdir ~/Test\ Site
cd ~/Test\ Site
```

Set up a virtual environment:

python3 -m venv venv
source venv/bin/activate

You should see (venv) at the beginning of your terminal prompt now.

Step 2: Installing Required Software¶

Install MkDocs and the Publisher plugin:
```
pip install mkdocs-publisher
```

Install Node.js packages (for optimization tools):

npm init -y
npm install --save-dev svgo html-minifier-terser postcss-cli uglify-js

Install Rust and Oxipng:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
cargo install oxipng

Follow the prompts during Rust installation.

Step 3: Configuring Your Site¶

Create a basic configuration file:
```
nano mkdocs.yml
```
Paste the following into the file:

site_name: Your Site Name
theme:
  name: material

plugins:
  - search
  - pub-meta
  - pub-blog
  - pub-obsidian
  - pub-social
  - pub-minifier
  - pub-debugger

nav:
  - Home: index.md

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences

copyright: "&copy; 2024 Your Name"

Replace "Your Site Name" and "Your Name" with your preferences.

Save and exit (press Ctrl+X, then Y, then Enter).

Step 4: Creating Content¶

Create a docs folder and an index file:

mkdir docs
echo "# Welcome to My Site" > docs/index.md

(Optional) Add a blog post:

mkdir docs/blog
echo "---
title: My First Blog Post
date: 2024-09-14
---

# My First Blog Post

Welcome to my blog!" > docs/blog/first-post.md

Step 5: Building and Serving Your Site¶

Build your site:
```
mkdocs build
```
Serve your site locally:
```
mkdocs serve -a localhost:5001
```
Open a web browser and go to http://localhost:5001 to see your site.

Step 6: Simplifying Future Use¶

Create an alias for easy startup:

Open your aliases file:
```
nano ~/.bash_aliases
```

Add this line:

alias serve-test-site='cd ~/Test\ Site && source venv/bin/activate && export PATH="$PWD/node_modules/.bin:$HOME/.cargo/bin:$PATH" && mkdocs serve -a localhost:5001'

Save and exit (Ctrl+X, then Y, then Enter).
Apply the changes:
```
source ~/.bash_aliases
```

Now, you can start your site anytime by just typing serve-test-site in the terminal.

Conclusion¶

You now have a basic MkDocs site with the Publisher plugin set up. To add more pages, create additional .md files in the docs folder and update the nav section in mkdocs.yml.

Remember to activate your virtual environment (step 1.3) each time you start a new terminal session to work on your site.

Happy documenting!