Wanting to add a blog to your already established MkDocs site? Are you using it as a blog already but haven't enabled the blog plugin? How do you format your already established posts so MkDocs will build with your new blog? All this and more...
MkDocs Blog Creation
I've been lugging my .md files between different static site generators, Markdown blogs, and other tooling for years. I had tried MkDocs multiple times but this time it stuck! I have it hooked into my local CI / CD and I host the static files up on Codeberg Pages, and I am thrilled that I am done searching🔎
My use case for MkDocs is a blog, a place to store docker compose examples, and a docs for personal documentation. My original folder structure worked great until my posts kept growing, this is when I went searching for a tool to organize them on MkDocs.
mkdocs/
├── docs
│ ├── blog
│ ├── docker
│ ├── docs
│ └── index.md
├── mkdocs.yml
└── README.md
If you want to enable the true blog experience with a landing page that shows your most recent posts, filter by tags, by month/years, then your folder structure must comply with the blog plugin and every .md file requires a new date: tag.
The folder structure matters. If you have no folder structure yet the blog plugin will create it for you. Otherwise move your posts into the following folder structure.
mkdocs/
├── docs
│ ├── blog
│ │ ├── index.md
│ │ └── posts
│ │ └── mkdocsBlogCreation.md
│ ├── docker
│ ├── docs
│ └── index.md
├── mkdocs.yml
└── README.md
Adding Post Date
No one has time to manually fill in the date for every post, let alone I have no clue when most of these were created. My initial though was to check my git log for when each file was created, but that only gets me the date of when I checked huge dumps of code into Codeberg. Second thought was stat the files for their creation date, but new system, fresh git pull so the creation date is also not accurate here. 🤔 Most of these files came from my NAS at some point, some were in really rough quick notes form, others were more flushed out reference docs. Maybe I can create a blog/posts reference list and for each post and find the corresponding file on my NAS where it was birthed from, copy the absolute path and add to said reference list. Bit of bash scripting and I should be able to stat all the files for the creation dates, and use sed to find a replace creation: on each posts header.
All Posts List
cd /mkdocs/docs/blog/posts
Find all markdown files within the directory, sort the list, and cut the trailing ./ off the file names.
find . -type f -name "*.md" | sort -n | cut -c 3- > ~/mkdocs-blog-post-list.txt
I headed over to the NAS and started digging in to the source material files. Birth: - ... 🤨 okay what-fug haha 🤣 Yup that was a quick dead end.
Fine! I will just use git log file creation and phone it in. I am working on a post and would rather be writing that than filling in header info 😜
git log creation
We can use git log to get the epoch of its source control, git log --diff-filter=A -- $file will get the information we want but not formatted.
Date: Sat Dec 21 05:40:04 2024 -0700
First we need to snag the month, day, year and format them.
If we echo our sample string out and manipulate it with cut to test the filter out:
echo "Date: Sat Dec 21 05:40:04 2024 -0700" | cut -d " " -f 5-6,8
We use the delimiter of -d " " which is the space between each column. Then use -f 5-6,8 to grab the columns 5 through 6 and 8, simple right?
Dec 21 2024 needs to be our MkDocs format of day, month, year in number representation 21-12-2024.
Date Sanitization
Dec 21 2024 needs three transform steps.
Decneeds to be converted to number representation" "spaces need to be converted to-dashesmonth / dateneed to be swapped 🔄
This can all be accomplished with the date command.
We first adjust our cut command above and use _DATE as its variable name
_DATE=$(cut -d " " -f 5-6,8). You can use the standard date command to transform the output of Dec 21 2024 into 21-12-2024 quite simply, date -d "$_DATE" +%Y-%m-%d ✨