Overview

This repo contains the code which is used to build my blog at <blog.mbedded.ninja>.

The static site generator Hugo is used to build the website from the files in this repo. Netlify is used to host the website, along with a few AWS services (built with serverless) to host an API/database for the shurikens.

Development

The recommended code editor is Visual Studio Code.

Follow the instructions here to install Hugo (using chocolatey to install is recommended when running Windows).

To start a development server that will watch for file changes (w), build drafts (D) and build future content (F):

$ hugo server -wDF

Sometimes hugo gets out of sync with the latest file changes. If this happens, you can force hugo to rebuild everything when detecting a file change (warning: this slows down build times):

$ hugo server -wDF --disableFastRender

There is a test page filled with different shortcode and style tests. It is located at /posts/test-page/.

To Build

To build site and place files in public directory:

$ hugo

To sync the Algolia index with the current state of the hugo site, make sure you've built the site by running hugo, and then:

yarn algolia

Directory Structure

content/ Markdown files which contain the content which creates the sites pages and posts.
layouts/
- shortcodes Hugo shortcodes.
  - calculators Contains the HTML/CSS/jQuery based interactive calculators which are embedded into certain pages.
old/ Deprecated content which is kept around just in case I need it again.
requirements/ Contains a requirements.txt used to create a Python virtual environment for running the various Python scripts in this repo.
scripts/ Useful Python scripts to automate some laborious tasks.

Broken Link Checking

I use the great LinkChecker.

You can install this with pipenv using:

$ pipenv install --two LinkChecker

Recommended VS Code Plugins

Code Spell Checker (prevents spelling mistakes). Additional dictionary definitions are included in vscode.code-workspace.
Vim (if you're a vim fan!)
EditorConfig for VS Code (promotes consistent coding styles, incl. indentation rules)
Better TOML: For syntax highlighting in the Hugo config file config.toml

Markdown Extensions

The syntax <www.google.com> can be used (instead of [www.google.com](www.google.com)) to include a link in where the displayed text is the same as the href.

Diagrams

Diagrams are typically drawn in LibreOffice Draw and then exported to .svg to display on a page. The Draw file (.odg) is usually located in the same content directory as the page the diagram is shown on.

woonjjang/blog