After wandering the world of static site generators (SSG), I came across an eye-catching, well-documented, and developer-friendly one focusing on documentation sites: Docusaurus. After diving a bit deeper into their documentation, I realized they have many out-of-the-box features, which I can try integrating into Silke, an SSG I wrote from scratch.
A few words about Docusaurus
It was amazingly quick to set a static site up and running with Docusaurus. With a single command, you can pull all the boilerplate code along with some examples to try it out: npm init docusaurus@latest my-website classic. Docusaurus also makes it extremely easy for developers to add new pages with intuitive directory structure, routed-based code, and hot reloading.
Overwhelmingly impressed by its features, I found a good one that can potentially add more flexibility and SEO optimization to Silkie.
Markdown Front matter support
For the time being, I planned to support 5 front matter fields: slug, title, hide_title, description, and tags. However, it was almost impossible to complete all of them in such a short amount of time. In fact, merely parsing the front matter already brought a major change to my codebase. Therefore, I decided to deliver only a prototype of this feature this week (check out its commit here).
GitHub Issues
GitHub Issues really helped me break the feature down into smaller solvable issues. I filed a major issue for Markdown Frontmatter support. This issue also tracks a list of smaller issues that constitute the feature.
To save myself from reinventing the wheel, I researched available Python libraries that can assist me with those tasks. In the end, Python Frontmatter helped me resolve the major issue. Silkie can now parse the front matter of each file and:
- Create a route-based build directory structure
- Set the title of the generated HTML document
- Set the description of the generated HTML documents
For example, if I have a Markdown file, named my-blog.md, below:
---
slug: blog/blog-post
title: "Lorem Ipsum Blog"
description: "This is a description"
tags: [blog, demo]
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
When it's passed to Silke, the build directory, dist/, should place the generated HTML file inside folder blog/:
The content of blog-post.html should look like this:
<!DOCTYPE html>
<html lang="en-CA">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="description" content="This is a description" />
<meta property="og:description" content="This is a description" />
<title>Lorem Ipsum Blog</title>
</head>
<body>
<h1>Lorem Ipsum Blog</h1>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet</p>
</body>
</html>
There's still a lot of development to do. I've filed separate issues for each requirement of the feature, so I'll probably know what to build next. It'd be wonderful if others can check them out and contribute to my project.
Top comments (0)