Towards a README for this website

This is for my own future reference and for anyone who might be interested in Obsidian, static websites, and deploying via Git.

Obsidian

These days, I like to use Obsidian to organize the content of my websites because I already use it for notes. I have a vault for each website, currently the one you are looking at and my archive of art and writing. I could just use any names for folders and files that feels right (so on the other site, the main folders are quasi-institutions and studies) but because this site is a weblog, I use posts as the folder to contain all my posts.

What my Obsidian looks like for this page on this site.

Plugins

If you've never used Obsidian, you should know that you are almost definitely going to want to install some plugins to customize it. Once these are all set up, I never think about them again, and so documenting it here is how I stop myself from reverse engineering my own system:

Git

This is the single most important and essential plugin. Not only does it store and version control my files but it is how I publish my website (using GitHub Actions -- more on that below). But see that up arrow in a circle, above where it says "vault backup"? When I push that it publishes my site.

Templater

This is a super common plugin that allows you to give some automatic structure to new documents. For me, a blog post has some essential stuff like a title, date, categories, but also the ability to pin a post to the front page or to keep it as a draft and not publish it. Some of these frontmatter properties are defined by mkdocs (more on that below).

A screenshot of my blog template. Pretty basic!

QuickAdd

QuickAdd is a little complicated but it's a way to create a blog post and put it in the correct folder posts and apply the correct template in one quick command.

Commander

This plugin is a way to add your own buttons onto the Obsidian interface. If you see the plus sign at the bottom of the left part of the Obsidian window: that is a button that will fire the QuickAdd command I created, thus creating a blog post in the right place.

mkdocs

mkdocs is a static site generator that's primarily intended for people to use it to do software documentation. But it's got a blog plugin and I have found it's potentially interesting for documenting your own practice (i.e. something like a folio).

I mainly write in Python when I can and so I am quite comfortable with all of the below. None of it gave me any trouble, all is a pretty straightforward use of Python.

First, just make sure mkdocs is installed on your computer.

pip install mkdocs

These are a couple other things to customize how I use mkdocs

pip install mkdocs-literate-nav # to edit my nav through obsidian
pip install mkdocs-material # for the layout
pip install mkdocs-obsidian-bridge # to be able to use Obsidian as CMS

The each site will want its own directory:

mkdocs new my-project # for me my-project was mkdocs-blog

The most important file is the configuration file, mkdocs.yml. Here is mine:

site_name: somethingilearned.today

docs_dir: !ENV [DOCS_DIR, '/path/to/obsidian/contents/of/my/blog'] # Where is your Obsidian vault?
site_url: !ENV [SITE_URL, 'https://somethingilearned.today'] # When you eventually deploy it

# These are the files in that docs_dir that I want to make sure aren't included in the build!
exclude_docs: |
.DS_Store
README.md
LICENSE
.gitignore
.git
.github
.vscode
templates
OLD

plugins:
  - tags
  - obsidian-bridge
  - blog:
    blog_dir: . # this uses 'posts' right in the root of docs_dir
    post_readtime: false # I don't like '2 minute read'
    post_date_format: "d MMM YYYY"
  - literate-nav: # https://oprypin.github.io/mkdocs-literate-nav/index.html
    nav_file: NAVIGATION.md

markdown_extensions:
  - sane_lists
  - pymdownx.blocks.caption
  - admonition
  - footnotes
  - toc: # right sidebar
    title: Contents

theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.top
    - navigation.indexes
    - navigation.sections
  palette:
    scheme: slate
    primary: white 
    accent: black
  font:
    text: Arimo # Georgia # Alegreya #Lato # Open Sans #Karla 
    code: Roboto Mono
  logo: assets/images/logo.png # Optional, see my file system
  favicon: assets/images/logo.ico # ditto

extra_css:
  - assets/stylesheets/extra.css # Optional, see my file system

There are a couple of places where I make custom configurations to the theme. They are the logo, a few extra styles, and also a small modification to the template.

GitHub

Now I create a Git repository for this mkdocs-blog directory and I rarely edit it. I keep it separate from my Obsidian vault, which is another repository, and which I am always editing.

I've got a GitHub Action workflow that runs whenever I push from my Obsidian Vault. It pulls the mkdocs configuration and then builds the site on GitHubs servers using that configuration plus my content files and publishes to a GitHub pages site, which is where it is hosted.