SimplSite

SimplSite is a simple server-side rendered website builder built with Deno.

Create dynamic websites using Markdown content, Handlebars templates, and a powerful plugin system for extending functionality.

Features

Server-side rendering for dynamic content
Markdown support with frontmatter for metadata
Handlebars templating with layouts and partials
Flexible routing based on content structure
Extensible plugin system
Built-in development server
Static asset handling

Installation

To use SimplSite, you need Deno installed on your system. If you haven't installed Deno yet, follow the instructions on the official Deno website.

You can run SimplSite directly using:

deno run --allow-read --allow-write --allow-net --allow-run jsr:@iamseeley/simpl-site/cli

For convenience, you can install SimplSite globally:

deno install --allow-read --allow-write --allow-net --allow-run -n simpl-site jsr:@iamseeley/simpl-site/cli

Quick Start

Create a new SimplSite project:
```
simpl-site my-website
cd my-website
```
Start the development server:
```
deno task dev
```
Visit http://localhost:8000 to see your website.

Project Structure

After initialization, your project will have the following structure:

my-website/
├── assets/
│   ├── css/
│   ├── js/
│   ├── images/
│   └── fonts/
├── content/
│   ├── blog/
│   ├── projects/
│   └── index.md
├── plugins/
├── templates/
│   ├── layouts/
│   └── partials/
├── config.ts
├── server.ts
└── deno.json

Configuration

The config.ts file is where you define your website's structure and behavior. Here's an example configuration:

import { WebsiteConfig } from "jsr:@iamseeley/simpl-site";
import TableOfContentsPlugin from './plugins/TableOfContentsPlugin.ts';
import LastModifiedPlugin from './plugins/LastModifiedPlugin.ts';
import { registerPluginType } from 'jsr:@iamseeley/simpl-site/plugin-registry';

// Register your plugins
registerPluginType("TableOfContentsPlugin", TableOfContentsPlugin);
registerPluginType("LastModifiedPlugin", LastModifiedPlugin);

// Configure your website
export const config: WebsiteConfig = {
  contentSources: [
    { path: "./content/blog", type: "blog", route: "blog/" },
    { path: "./content/projects", type: "project", route: "projects/" },
    { path: "./content", type: "page", route: "" },
  ],
  plugins: [
    {
      name: "TableOfContentsPlugin",
      options: {
        routes: ["/plugin-example", "/plugin-docs"],
        minDepth: 2,
        maxDepth: 4
      }
    },
    {
      name: "LastModifiedPlugin",
      options: {
        contentTypes: ["blog"],
        routes: ["/about"]
      }
    }
  ],
  defaultContentType: "page",
  templateDir: "./templates",
  customPluginsDir: "./plugins",
  assetsDir: "./assets",
  siteTitle: "Simpl Site",
};

Content Creation

Create your content using Markdown files in the content/ directory. You can use frontmatter to add metadata to your content:

---
title: My First Post
date: 2023-07-08
tags: [web, development]
---

# Welcome to My First Post

This is the content of my post.

Templating

SimplSite uses Handlebars for templating. Here's an example of the 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}}</title>
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  {{> header siteTitle=siteTitle}}
  <main>
    {{{body}}}
  </main>
  <footer>
    <p>Powered by simpl-site</p>
  </footer>
  <script src="/js/main.js"></script>
</body>
</html>

Note how you can access metadata from your Markdown frontmatter using {{metadata.title}} and pass data to partials like {{> header siteTitle=siteTitle}}.

Plugins

SimplSite's plugin system allows you to extend and modify content processing. Plugins can transform content, add metadata, and extend template contexts.

Creating a Plugin

To create a plugin, implement the Plugin interface:

import type { Plugin, Metadata, PluginContext } from "jsr:@iamseeley/simpl-site";

export default class MyCustomPlugin implements Plugin {
  name = "MyCustomPlugin";

  constructor(private options: Record<string, unknown>) {}

  async transform(content: string, context: PluginContext): Promise<{ content: string; metadata?: Metadata }> {
    // Modify content or add metadata here
    const modifiedContent = `Modified: ${content}`;
    return { 
      content: modifiedContent, 
      metadata: { customField: "value" } 
    };
  }

  async extendTemplate(templateContext: Record<string, unknown>): Promise<Record<string, unknown>> {
    // Add or modify data available in templates
    return { 
      ...templateContext, 
      customVariable: "value" 
    };
  }
}

Using Plugins

Create your plugin in the plugins/ directory.

import MyCustomPlugin from './plugins/MyCustomPlugin.ts';
registerPluginType("MyCustomPlugin", MyCustomPlugin);

Add the plugin to your configuration:

plugins: [
  {
    name: "MyCustomPlugin",
    options: {
      // Any options your plugin needs
    }
  }
]

Development

To start the development server:

deno task dev

Deployment

There are several options for deploying your SimplSite project to production. Here are some recommended approaches:

Deno Deploy

Deno Deploy is the easiest and fastest way to deploy your Deno applications. It's specifically designed for Deno and offers seamless integration.

To deploy your SimplSite project on Deno Deploy:

Sign up for a Deno Deploy account if you haven't already.
Create a new project in the Deno Deploy dashboard.
Link your GitHub repository or upload your project files.
Set the entry point to your server.ts file.
Configure any necessary environment variables.

Deno Deploy will automatically handle the deployment and provide you with a URL for your site.

Other Cloud Platforms

You can also deploy your SimplSite project to various cloud platforms that support Deno:

Digital Ocean: Use a Droplet or App Platform to host your Deno application.
AWS Lightsail: Set up a VPS instance to run your Deno server.
Google Cloud Run: Deploy your Deno app as a containerized application.
Cloudflare Workers: With some adjustments, you can run your SimplSite project on Cloudflare's edge network.
Kinsta: Offers Deno hosting as part of their application hosting services.

For these platforms, you'll typically need to:

Set up a server or container environment.
Install Deno on the server.
Copy your project files to the server.

Run your server.ts file using a command like:

deno run --allow-read --allow-write --allow-net server.ts

Set up a reverse proxy (like Nginx) if needed.
Configure any necessary environment variables.

Self-Hosting

If you prefer to self-host, you can run your SimplSite project on any VPS or dedicated server that allows you to install Deno. Follow these general steps:

Set up your server and SSH access.
Install Deno on the server.
Clone or copy your project files to the server.

Install and configure a process manager like PM2 to keep your app running:

npm install -g pm2
pm2 start --interpreter="deno" --interpreter-args="run --allow-read --allow-write --allow-net" server.ts

Set up a reverse proxy with Nginx or Apache to handle HTTPS and domain routing.

Contributing

Contributions are very welcome!

License

SimplSite is released under the MIT License. See the LICENSE file for details.

       😊
Enjoy 👉👈

pomdtr / simpl-site