Introducing Lumocs: A Modern Documentation Engine based on Deno and Lume

by Hexagon, 2023-10-06 4 minutes read documentation lumocs deno lume javascript typescript markdown

Meet Lumocs, a documentation generator powered by JavaScript through Deno and Lume. This guide will walk you through the essential steps to set it up, create your first documentation page, and deploy your site.

If you want a quick showcase, check out the Lumocs Documentation, which is generated by Lumocs itself.

Features

• Design and layout tailored for documentation.
• Automatic light/dark mode by user preference.
• No configuration needed, works great and looks great out of the box.
• Generates a documentation website from markdown-files, using extended markdown-it syntax.
• Easy to customize using _data.json and the _includes-folder.
• Mobile-responsive design.
• Ready for deployment on GitHub Pages.
• Hierarchical navigation with up to three content levels.
• Built with modern tools: Deno and Lume.

Prerequisites

Before we jump into Lumocs, ensure you have Deno installed on your system. Lumocs requires Deno version 1.37 or higher to function correctly. If you haven't installed Deno yet, follow the official instructions to get it up and running. If you're new to Deno and want to learn more about its features, you can also check out my post on Getting Started with Deno.

Fast Track Setup

If you're eager to get started quickly with Lumocs, you can use the following command to initialize your Lumocs project:

deno run -A https://deno.land/x/lumocs/init.ts <folder-name>

Replace <folder-name> with the name of the folder where you want to set up your Lumocs project. This command will create the basic project structure and essential files. Enter the newly generated folder and run:

deno task serve

This will launch a local server, making your site accessible at http://localhost:8000.

Adding Content

Once you have set up your Lumocs project, you are ready to create some content. You will already have a template src/index.md which is generated to /index.html. To create more content, add new Markdown files for each page or section of your documentation.

Each Markdown file should start with a front matter block, specifying metadata such as the page title and navigation order. Here's an example:

---
title: "Page Title"
nav_order: 2
---

## Heading

This is the markdown content.

If you want to create a hierarchy of pages, you add parent: "Title of parent" to the front matter of the child page.

The Details

While the initialization script above creates all the necessary files automatically, if you prefer a manual setup, here's how to organize your Lumocs project files effectively:

/                          # Your repository root
├── /docs                  # The documentation folder
│   ├── _config.ts         # Lume configuration file
│   ├── deno.json          # Deno configuration file
│   └── /src               # Documentation source
│       ├── _data.json     # Global variables
│       ├── index.md       # Documentation index, will become index.html
│       └── <other pages>  # Additional documentation pages

In this structure, all Lumocs-related files are placed within the /docs subfolder. The actual content and global variables are located in the /docs/src subfolder.

deno.json

The deno.json file controls which version of Lume and Lumocs should be used and sets up the scripts to build your site. Here's an example configuration:

{
  "tasks": {
    "lume": "echo \"import 'lume/cli.ts'\" | deno run --unstable -A -",
    "serve": "deno task lume -s --port=8000"
  },
  "imports": {
    "lume/": "https://deno.land/x/lume@v1.19.1/",
    "lumocs/": "https://deno.land/x/lumocs@0.0.16/"
  }
}

Make sure to match the import versions with the latest version off Lume and Lumocs.

_config.ts

In the _config.ts file, you'll set the public URL of your site to ensure the sitemap displays complete URLs. Advanced users can also activate additional Lume plugins here. Here's a basic configuration:

import lume from "lume/mod.ts";
import lumocs from "lumocs/mod.ts";

const siteUrl = "https://url.of.site";

const site = lume({
  src: "src",
  location: new URL(siteUrl),
});

site.use(lumocs());

// OPTIONAL: site.copy("img")

export default site;

Note the commented-out line, which instructs Lumocs to copy the contents of an img directory located within your src/ folder to the resulting output directory when your website is built. This step ensures that any images or assets in the img directory are included in your documentation website.

src/_data.json

Think of src/_data.json as the global configuration for your site. Parameters in this file serve as the default front matter for each generated page. Here's an example:

{
  "lang": "en",
  "layout": "page.njk",

  "metas": {
    "title": "=title",
    "site": "Site Name",
    "lang": "en",
    "description": "=description"
  },

  "top_links": [
    {
      "icon": "fab fa-github",
      "title": "GitHub Repository",
      "url": "https://github.com/hexagon/lumocs"
    },
    {
      "icon": "fab fa-npm",
      "title": "NPM Library",
      "url": "https://npmjs.com"
    }
  ],

  "nav_links": [
    {
      "title": "GitHub Repository",
      "url": "https://github.com/hexagon/lumocs"
    },
    {
      "title": "NPM Library",
      "url": "https://npmjs.com"
    }
  ]
}

Compiling Your Site

When you're ready to compile your site for deployment, run the following command:

deno task lume

This command will render your site into a new subfolder called _site within your /docs directory. The lume command is especially useful for deploying your site, and it's run automatically if you use the provided GitHub Pages workflow.

Deploying Your Site

Now you can either deploy your site manually, or utilize GitHub Pages.

There's an example workflow included at /demo-repository/.github/workflows/deploy-pages.yml in the Lumocs GitHub repository. This workflow shows you how to set up GitHub Actions to handle the deployment for you.

1. Copy the deploy-pages.yml from the /demo-repository/.github/workflows/ directory to your project's .github/workflows/ directory.
2. In your GitHub repository, navigate to Settings.
3. Under the Pages section, set the source to GitHub Actions.

This configuration will automatically build and deploy your site to GitHub Pages whenever you push to your main branch.

Resources

• Lumocs Documentation.
• Lume.

---