making a blog LOCAL making a blog

Create/document a (simpler) method for creating a static web site to upload to github to be used as a blog or a technical document.

o fast

o easy

o simple(r)

Developers, technical writers, and anyone needing a simple blog solution.

When I looked into enabling "GitHub Pages" to create a simple blog, I was a little put off at how "difficult" it was. -i.e. you need a client app `Jekyll` or a `nojekyl` file and/or this and that and I came to the conclusion it was too complicated! I have a text editor and I type my notes in a really simple markdown style which is easy to read and contains all the stuff I need (headings, titles, bold, italic, code blocks, etc.) so, I decided to create a bit simpler method to create static html files from my simple markdown text files.

I typically create my notes/files like:

 date: <a date>
 author: <where or who I got it from>
 title: "<title>"

 # title

 # header
 some text

 *bold*
 _italic_
 ...
A while ago I wrote myself a little program to convert simple markdown syntax items into mandoc (my program is to allow me to write man pages) so my thought was that since `mandoc` can export to HTML--and it's already installed on many *nix machines already--why can I not use that!?

Step 1 : Getting `md2mdoc`

Grab my utility--and install it--to convert markdown files to mdoc files so `mandoc` can read them.

 git clone https://github.com/JohnKaul/md2mdoc.git
 ...
 doas make install

Step 2 : Create a repository

Head over to GitHub and create a new public repository named "username.github.io", where `username` is your username on GitHub.

Step 3 : Clone the repository

Go to the folder where you want to store your project, and clone the new repository:

 git clone https://github.com/username/username.github.io
Open your new project folder.

Step 4 : Create Something

Create some text:

 vim myblog.md

myblog.md contents:

 date: Jun 30 2025
 author: John Kaul
 title: "my blog"

 # My Blog
 This is some text which other people beside me will find important.

Fetch some pretty (for your html files).

 fetch -o style.css https://man.openbsd.org/mandoc.css

Step 5 : Convert your markdown to html

 % md2mdoc myblog.md index.1 && mandoc -Thtml -I os='' -Otoc,style=style.css index.1 > index.html && rm index.1

Step 6 : Push it

Add, commit, and push your changes:

 git add --all
 git commit -m "Initial commit"
 git push -u origin main

Step 7 : Enable pages

Go to your project's setting on GitHub and enable pages. Choose the settings you want and the URL for your blog will be located at the top of the page.

Jun 30 2025