after a month or two of tinkering on val.town, i found myself really enjoying working with Deno (val.town uses the Deno runtime to run your JS/TS). i've enjoyed Deno so much, i decided to make a website builder with it.
it's called simpl-site: it lets you create dynamic websites with markdown content, handlebars templates, and a plugin system for transforming content and extending templates.
this website is powered by simpl-site!
it's my first JavaScript Registrty (JSR) package: @iamseeley/simpl-site, and this is my first "technical" blog post!
in this post i want to share a little background on the project, then dive into the code to explore how it all works. i'll wrap it up with next steps for the project.
i like building the thing that builds the thing
i have a confession to make.
i redo my personal website way too often, and sometimes when i do... i end up making the tool that builds the site. i spend all my time building the 'thing' that builds the 'thing.' i admit this might not be the healthiest / most efficient use of my time, but i think it can be pretty rewarding when it all comes together, and you get your website running with something you've created.
for this project, what started as a website refresh turned into an exploration of server-side rendering, the Deno ecosystem, and publishing modules via JSR.
static site generation to server-side rendering
i think it's worth mentioning simpl-site's predecessor: go-forth, a static site generator i wrote in Go. go-forth was my first adventure in creating a website builder, and it laid the groundwork for many of the ideas i've implemented in simpl-site.
go-forth taught me a lot about structuring a site generator, handling markdown content, and managing templates.
it uses a similar concept of collections for organizing content and uses Go's html/template package for templating. while go-forth is a static site generator, simpl-site takes a different approach by implementing server-side rendering and a plugin system.
simpl-site overview
before we get into the code specifics, let's take a high-level look at how simpl-site is built and how it leverages some of Deno's features.
key components and technologies:
-
Deno: simpl-site is built on Deno, which provides a secure runtime for JavaScript and TypeScript. this allows us to use modern ES6+ features and TypeScript out of the box, without need for transpilation.
-
Deno.serve: simpl-site uses Deno's serve function, which provides a minimal way to create an HTTP server. this function handles incoming requests and routes them to the appropriate handler.
-
file system operations: simpl-site uses Deno's built-in APIs for file system operations (Deno.readTextFile, Deno.writeTextFile, etc.) to read markdown content, templates, and other assets.
-
markdown processing: simpl-site uses Marked for markdown parsing and compiling.
-
Handlebars templating: for HTML templating, simpl-site uses Handlebars. this allows for dynamic content insertion and reusable template components.
-
plugin system: simpl-site implements a plugin architecture that allows users to transform content or extend templates, providing a flexible way to customize the site generation process.
-
caching: to improve performance, simpl-site includes a caching system. this reduces the need to re-process unchanged content on every request.
-
static file serving: for assets like CSS, JavaScript, and images, simpl-site includes functionality to serve static files.
-
TypeScript: simpl-site is written in TypeScript.
each request goes through a pipeline of processing steps: routing, content retrieval, markdown processing with marked, plugin transformations, template rendering, and finally, response sending.
code deep dive: anatomy of a page request
let's walk through the lifecycle of a page request in simpl-site, following the process from initial request to final rendered output. this will take us through the key components of the SimplSite
class and show how they work together to build a dynamic website.
1. handling the incoming request
when a request comes in, it's first handled by the handleRequest
method:
async handleRequest(path: string): Promise<{ content: string | ReadableStream<Uint8Array>;
contentType: string; status: number; size?: number }> {
// Check for static file first
const staticFile = await this.serveStaticFile(path);
if (staticFile) {
return { ...staticFile, status: 200 };
}
// If not a static file, proceed with content rendering
path = path.replace(/^\//, '');
if (path === '') {
path = 'index';
}
const originalPath = path;
path = path.endsWith('.md') ? path : path + '.md';
let result;
for (const source of this.contentSources) {
if (originalPath.startsWith(source.route)) {
const contentPath = path.slice(source.route.length);
result = await this.renderContent(contentPath, source.type,
'/' + originalPath);
break;
}
}
if (!result) {
result = await this.renderContent(path, this.defaultContentType,
'/' + originalPath);
}
return result;
}
this method first checks if the request is for a static file using the serveStaticFile
method. if it is, it serves the file directly. if not, it determines the appropriate content source and calls renderContent
to generate the dynamic content.
2. serving static files
the serveStaticFile
method efficiently handles static file requests:
private async serveStaticFile(path: string): Promise<{ content: ReadableStream<Uint8Array>; contentType: string; size: number } | null> {
const relativePath = path.startsWith('/') ? path.slice(1) : path;
if (!this.staticFilePaths.has(relativePath)) {
return null;
}
const fullPath = join(this.assetsDir, relativePath);
try {
const file = await Deno.open(fullPath, { read: true });
const fileInfo = await file.stat();
const mimeType = contentType(extname(fullPath)) || "application/octet-stream";
return {
content: file.readable,
contentType: mimeType,
size: fileInfo.size
};
} catch (error) {
console.error(`Error opening static file ${fullPath}:`, error);
return null;
}
}
this method checks if the requested file exists in the pre-cached staticFilePaths
set. if it does, it opens the file as a readable stream, determines its MIME type, and returns the necessary information for serving the file.
3. rendering content
if the request is for dynamic content, the renderContent
method is called. this method orchestrates the entire process of retrieving, processing, and rendering the content:
async renderContent(path: string, type: string, route: string): Promise<{ content: string; contentType: string; status: number }> {
// ... (caching logic)
const content = await this.getContent(path, type);
const { content: processedContent, metadata } = await this.processContent(content, type, route);
let templateContext: TemplateContext = {
content: processedContent,
metadata: metadata,
route: route,
siteTitle: this.siteTitle,
};
// Allow plugins to extend template context
for (const plugin of this.plugins.values()) {
if (plugin.extendTemplate) {
templateContext = await plugin.extendTemplate(templateContext);
}
}
const renderedContent = await this.templateEngine.render(type, templateContext);
// ... (caching and return logic)
}
within renderContent
, three crucial steps occur:
3.1 retrieving the content
the getContent
method is called to fetch the raw content:
async getContent(path: string, type: string): Promise<string> {
const source = this.contentSources.find(src => src.type === type);
if (!source) {
throw new Error(`Unknown content type: ${type}`);
}
const fullPath = join(source.path, path);
return await Deno.readTextFile(fullPath);
}
this method finds the appropriate content source based on the content type and reads the file from the filesystem.
3.2 processing the content
once the raw content is retrieved, the processContent
method is called to process it:
async processContent(content: string, type: string, route: string): Promise<{ content: string; metadata: Metadata }> {
let { content: processedContent, metadata } = await this.markdownProcessor.execute(content);
const context: PluginContext = {
contentType: type,
route: route,
templateDir: this.templateDir,
contentSources: Object.fromEntries(
this.contentSources.map(source => [source.type, source.path])
),
siteUrl: this.siteUrl
};
for (const plugin of this.plugins.values()) {
if (plugin.transform) {
const result = await plugin.transform(processedContent, context);
processedContent = result.content;
if (result.metadata) {
metadata = { ...metadata, ...result.metadata };
}
}
}
return { content: processedContent, metadata };
}
this method first processes the markdown content, then applies each plugin's transform function in sequence. this allows plugins to modify both the content and metadata, providing a way to extend the site's functionality.
3.3 rendering the template
after processing the content, renderContent
calls the render
method of the TemplateEngine class to render the final HTML:
const renderedContent = await this.templateEngine.render(type, templateContext);
the TemplateEngine's render
method handles the actual rendering:
async render(templateName: string, context: Record<string, unknown>): Promise<string> {
console.log(`Rendering template: ${templateName}`);
try {
const templatePath = join(this.config.baseDir, `${templateName}${this.config.extname}`);
const layoutPath = join(this.config.baseDir, this.config.layoutsDir, `${this.config.defaultLayout}${this.config.extname}`);
if (!await exists(templatePath)) {
throw new Error(`Template not found: ${templatePath}`);
}
const template = await this.getCompiledTemplate(templatePath);
let result = template(context);
if (await exists(layoutPath)) {
const layout = await this.getCompiledTemplate(layoutPath);
result = layout({ ...context, body: result });
}
console.log(`Template rendered successfully: ${templateName}`);
return result;
} catch (error) {
console.error(`Error rendering template ${templateName}:`, error);
throw error;
}
}
this method compiles the template (or retrieves it from cache), renders it with the provided context, and then wraps it in a layout if one is specified. it also includes error handling to provide feedback if something goes wrong during the rendering process.
4. caching for performance
to improve performance, simpl-site implements a caching system:
private shouldUseCache(path: string): boolean {
if (!this.config.caching?.enabled) {
return false;
}
if (this.config.caching.excludedRoutes) {
return !this.config.caching.excludedRoutes.some(route => path.startsWith(route));
}
return true;
}
this method determines whether a particular path should be cached based on the configuration. it allows for fine-grained control over caching, including the ability to exclude specific routes.
by following this process for each request, simpl-site can efficiently handle requests for both static and dynamic content, apply plugins, render templates, and serve the resulting pages or files.
for more visual readers, here's a diagram depicting the process
extending simpl-site: plugins and template helpers
one of the most useful features of simpl-site is its extensibility through plugins and template helpers.
what can plugins do?
plugins in simpl-site can:
-
transform content: modify your markdown content before it's rendered
-
extend templates: add new data or functions to your handlebars templates
plugin system
simpl-site uses a plugin registry to manage and load plugins dynamically. here's how it works:
import type { Plugin } from "../types.ts";
const pluginRegistry: Record<string, new (options?: Record<string, unknown>) => Plugin> = {};
export function registerPluginType(name: string, pluginClass: new (options?: Record<string, unknown>) => Plugin) {
pluginRegistry[name] = pluginClass;
}
export function getPluginClass(name: string): new (options?: Record<string, unknown>) => Plugin {
const pluginClass = pluginRegistry[name];
if (!pluginClass) {
throw new Error(`Plugin ${name} not found in registry`);
}
return pluginClass;
}
this system allows you to register plugins and retrieve them by name, enabling a flexible and extensible architecture.
creating a plugin
let's look at how to create a plugin. we'll use a simplified version of the ContentListPlugin
that i use in this website as an example. this plugin generates HTML lists of content items.
here's a basic implementation of the ContentListPlugin
:
import type { Plugin, PluginContext } from "simpl-site";
export default class ContentListPlugin implements Plugin {
name = "ContentListPlugin";
async transform(content: string, context: PluginContext): Promise<{ content: string }> {
// Check if we're on a route that should display a content list
if (context.route === "/posts" || context.route === "/projects") {
// Generate a list of content items (simplified for this example)
const listHtml = this.generateListHtml(context.route);
// Append the list to the existing content
content = `${content}\n${listHtml}`;
}
return { content };
}
private generateListHtml(route: string): string {
// This is a simplified example. In a real plugin, you'd fetch and process actual content.
const items = [
{ title: "Item 1", date: new Date() },
{ title: "Item 2", date: new Date() },
];
let html = "<ul>";
for (const item of items) {
html += `<li>${item.title} - ${item.date.toDateString()}</li>`;
}
html += "</ul>";
return html;
}
}
this plugin demonstrates several key concepts:
-
implementing the plugin interface: the class implements the
Plugin
interface fromSimplSite
, which requires aname
property and atransform
method. -
the transform method: it receives the current content and a context object, and returns modified content. here's what it does:
- it checks the current route to decide whether to add a content list.
- if appropriate, it generates an HTML list and appends it to the existing content.
- it returns an object with the modified content.
-
using the context: the
PluginContext
provides information about the current request, including the route. in a more complex plugin, you could use other properties of the context, such ascontentSources
to access actual content files. -
generating content: the
generateListHtml
method is a simplified example of how you might generate HTML to inject into the page. in a real plugin, this would involve reading and processing actual content files.
to use this plugin, you would register it and add it to your simpl-site configuration:
import { WebsiteConfig } from "simpl-site";
import { registerPluginType } from "simpl-site/plugin-registry";
import ContentListPlugin from "./plugins/ContentListPlugin.ts";
registerPluginType("ContentListPlugin", ContentListPlugin);
export const config: WebsiteConfig = {
// ... other config options ...
plugins: [
{
name: "ContentListPlugin",
options: {}
},
],
// ... more config options ...
};
this example demonstrates the basic structure of a simpl-site plugin. the transform
method is called for each page, allowing you to modify or extend the content as needed. by implementing more complex logic in the transform
method and utilizing the full PluginContext
, you can create even more powerful plugins!
template helpers
template helpers are functions you can use in your Handlebars templates to perform operations or fetch data. here's an example of defining template helpers:
export const config: WebsiteConfig = {
// ... other config options ...
templateHelpers: {
getCurrentRoute: function(context: any) {
const route = context.route || '/';
return route;
},
eq: function(a: any, b: any) {
return a === b;
},
formatDate: function(dateString: string) {
const date = new Date(dateString);
const monthName = monthNames[date.getMonth()];
const day = date.getDate();
const year = date.getFullYear();
return `${monthName} ${day}, ${year}`;
}
}
};
you can then use these helpers in your templates. here's how you might use the getCurrentRoute
helper in a header partial:
<header>
<h4><strong>tseeley.com</strong></h4>
<nav>
<a href='/'>home</a>
<a href='/posts'>posts</a>
<a href='/projects'>projects</a>
<a href='/about'>about</a>
</nav>
{{#with (getCurrentRoute this) as |currentRoute|}}
{{#if (eq currentRoute "/index")}}
<!-- Special content for the index page -->
{{/if}}
{{/with}}
</header>
this example uses the getCurrentRoute
helper to determine the current route and potentially display different content based on that route.
by leveraging plugins and template helpers, you can significantly extend the functionality of your simpl-site project, customizing it to meet your specific needs.
a simplSite instance
you can visit the README for detailed setup and deployment instructions!
project structure
after initializing a new simpl-site project, your directory structure will look something like this:
my-website/
├── assets/
├── content/
├── plugins/
├── templates/
├── config.ts
├── server.ts
└── deno.json
configuring your simpl-site
the simpl-site configuration lives in the config.ts
file. this is where you define your website's structure and behavior.
let's look at the key configuration options:
import { WebsiteConfig } from "simpl-site";
export const config: WebsiteConfig = {
contentSources: [
{ path: "./content", type: "page", route: "" },
{ path: "./content/posts", type: "post", route: "posts/" },
{ path: "./content/projects", type: "project", route: "projects/" },
],
plugins: [
// Your plugins configuration
],
defaultContentType: "page",
templateDir: "./templates",
customPluginsDir: "./plugins",
assetsDir: "./assets",
siteTitle: "My Simpl Site",
templateHelpers: {
// Your custom template helpers
},
caching: {
enabled: true,
excludedRoutes: ['/dynamic-content']
}
};
here's what each of these options does:
contentSources
defines where your content is located and how it should be routed.plugins
specifies which plugins to use and their configurations.defaultContentType
sets the default type for content if not specified otherwise.templateDir
points to the directory containing your handlebars templates.customPluginsDir
specifies a directory for custom plugins.assetsDir
points to the directory containing static assets.siteTitle
sets a global site title.templateHelpers
allows you to define custom handlebars helpers.caching
configures the caching behavior.
note how the contentSources
are configured:
simpl-site uses content sources to define how files are served. for example:
{ path: "./content", type: "page", route: "" }
means that files directly in the ./content
directory will be served at the root of your site.
other content sources, for different content types like posts and projects, can be nested under their respective routes.
adding content
to create content add markdown files in the content/
directory.
here are some examples:
content/index.md
will be your home pagecontent/about.md
will be served at/about
content/posts/first-post.md
will be served at/posts/first-post
you can use frontmatter to add metadata to your content:
---
title: Welcome to My Site
date: 2023-07-08
tags: [welcome, intro]
---
# Welcome to My Site
This is the content of my home page.
creating templates
simpl-site uses Handlebars for templating.
here's an example of a base layout:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{metadata.title}} | {{siteTitle}}</title>
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
{{> header}}
<main>
{{{content}}}
</main>
{{> footer}}
</body>
</html>
JSR for distribution
i published the simpl-site module to JSR because it simplifies the development and distribution process for TypeScript projects. JSR is designed to work with multiple runtimes, including Node.js, Deno, and browsers, but still maintains backwards compatibility with npm.
the combination of TypeScript-first development, multi-runtime support, and npm compatibility made JSR an ideal choice for distributing simpl-site.
Smallweb
i'm a big fan of pomdtr's project Smallweb. it's a web server based on deno, that lets you create your own little self-hosted serverless platform. you "host websites from your internet folders" (Smallweb maps domains to folders in your filesystem).
simpl-site is compatible with Smallweb! by adding the --smallweb flag to simpl-site's init commands, you initialize a simpl-site project with a main.ts
file that's structured appropriately for serving a website via Smallweb.
pomdtr simplified the integration further and made simpl-site a Smallweb plugin.
if you already have Smallweb installed you can navigate to your Smallweb folder, and run the following command:
deno install -Agf jsr:@iamseeley/simpl-site/smallweb-simpl-site
smallweb simpl-site
this sets up a simpl-site project within your Smallweb environment.
what's next?
simpl-site is mostly a personal project, but it's also a tool i hope others will find useful. i'd love for people to try it and give me feedback so i can improve it!
moving forward, i'm planning on experimenting with new plugins, more complex sites, more advanced ssr techniques, and implementing a testing suite.
stay tuned for updates!