---
title: "Updated Website Install Guide"
publish: true
---

# 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

1. Open your terminal.

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

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

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

2. Install Node.js packages (for optimization tools):
   ```
   npm init -y
   npm install --save-dev svgo html-minifier-terser postcss-cli uglify-js
   ```

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

1. Create a basic configuration file:
   ```
   nano mkdocs.yml
   ```

2. Paste the following into the file:

   ```yaml
   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: "© 2024 Your Name"
   ```

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

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

## Step 4: Creating Content

1. Create a docs folder and an index file:
   ```
   mkdir docs
   echo "# Welcome to My Site" > docs/index.md
   ```

2. (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

1. Build your site:
   ```
   mkdocs build
   ```

2. Serve your site locally:
   ```
   mkdocs serve -a localhost:5001
   ```

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

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

2. 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'
   ```

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

4. 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!