I wrote a static site generator for my own personal site. I've been using it for over 10 years, and it's gone through several major refactors / redesigns. A few comments:<p>1. Template system<p>There are tons of different template systems out there for things like the "shortcodes" in the article.<p><pre><code> {{youtube id="123asdf4" /}}
</code></pre>
My conclusion is that the correct way to do this is with custom tags,<p><pre><code> <embed-youtube id="123asdf4"></embed-youtube>
</code></pre>
I apologize for the verbosity... but this is completely valid HTML5, and you do not need anything but an ordinary HTML5 parser to parse this. This maximizes your choices for the libraries you use in the static site generator and it maximizes the level of support in whatever editor you choose to author the site in. For example, you can just use the HTML mode in Vim or Emacs, or you can use VS Code, TextMate, Sublime Text, etc. and get a ton of features: syntax highlighting, indenting, etc.<p>While on the surface it looks verbose because of the closing tag, in most editors, you only have to press a key or two to close the tag. HTML5, strictly speaking, does not support self-closing tag syntax for custom tags. That syntax is only supported for void elements. There are only 16 void elements in HTML5.<p>I use "prefix-suffix" syntax to avoid ambiguity... any tag with a hyphen is obviously a custom tag.<p>2. Routing<p>Something you can use to tackle the routing complexity is to place your source files in the same path as the canonical URL. You only need routes for generated content, like index pages and such.<p>3. Index data<p>You'll naturally want to generate indexes and create previews for links. I suggest that you start by looking at the schema.org schema for web pages and work with a useful subset of that. This way, you can generate indexes on your web page using the same exact data, same exact schema, that you use for the JSON-LD data you provide for search engines like Google.<p>This is a minor point, but it reduces duplicated effort between the code for generating content for your website and the code for generating JSON-LD metadata.<p>Don't dive too deep into the schema.org schema, just take a couple bits and pieces that you need, and refer to the feature guides in Google's documentation:<p><a href="https://developers.google.com/search/docs/guides/intro-structured-data" rel="nofollow">https://developers.google.com/search/docs/guides/intro-struc...</a>