156 lines
3.3 KiB
Markdown
156 lines
3.3 KiB
Markdown
---
|
|
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! |