Markdown CMS with Svelte and Flowbite

This site works by leveraging Markdown for Context Management, and Svelte framework for building self-contained static pages.

Static Site Generators (SSG)

The idea of compiling static website looks promising and powerful, as a lot of tasks can be offloaded to compiler and build time:

• cross-checking links
• fetching data from external providers
• making page summaries with LLMs

And in case of errors, it fails on compile time, instead of in runtime for the user.

There are a plenty of SSG, collectively known as jamstack, which splits into two archetypes:

• based on templates, like Hugo
• based on components, like Svelte

Despite the magnitude of options finding the right one seems challenging:

• enforced folder structure
• "rich" templating syntax and extensions
• multiple files for the simplest projects, and theming capabilities
• front-matter and duplication (title, description)

The difference is how HTML is generated, either with one or more template languages, or with front-end frameworks.

Key Requirements

• compile/publish split with compile-time optimizations
• simple to operate public version
• should work on mobile without internet connection
• content automation allowing fetching data from different sources with API and/or scrapers
  • APIs are usually badly documented and is a subject to change
  • Scrapers are fragile

Development Journey

Obstacles, discoveries and limitations:

• wrongly assumed that picking SSG and using would be much simpler
• inconsistency of parsing link references
  • remark-parser behavior change from 8.x to 9.x (switch to micromark)
  • mdsvex uses remark-parser 8.x
• remark being overcomplicated compared to marked
  • https://npmtrends.com/markdown-it-vs-marked-vs-remark-parse
  • https://github.com/markdown/markdown.github.com/wiki/Implementations
  • https://medium.com/@logosnikita/how-i-chose-markdown-parser-97190a59fa5d
• Markdown parsers rabbit hole
  • Different language definitions, such as CommonMark and GitHub Markdown
  • Multiple solutions even within one language
• Remark
  • The most used (active) one is remark framework for JavaScript
  • AST and plugins, which seems great
• Parsing Markdown is only the beginning, assembling a working site out of it requires more work (and maintenance).
• Idea to reuse SSG, such as Svelte
• mdsvex journey and parsing Markdown with link references
• syntax highlighting and diagrams
  • mermaid is not supported on server side

Implementation

Implemented features and ideas for future development.

Building blocks:

• marked, Markdown processor and HTML renderer
• svelte, a free and open-source component-based front-end software framework
• flowbite, Tailwind CSS component library
• tailwind, a utility-first CSS framework

Custom-built extensions:

• folder structure
• markdown directives and extensions: poi, route, meta, git

Search Engines Optimization

A proper SSG engine is expected to handle SEO topics, such as:

• minimize CSS and JS bundles
• add metadata to each page, such as title and description
• handle broken links
• generate sitemap and feeds
• content migration to different addressing schema
• content navigation and organization (folders, breadcrumbs, subfolders)