Building a technical documentation static site for open source projects

Eleventy

Documentation is an important aspect of software development, design, and other aspects of tech. All codebase requires some form of documentation. From a simple README to full documentation.

It becomes necessary to use a nice & scalable system to generate, maintain, and deploy the documentation in some projects. That’s where “Static Documentation Generators” come in handy. They are easy to use, versatile, and extremely user-friendly. They are mostly used to document APIs, database schemas, and other information by organizations.

Static Site Generator

A static site generator is a tool that generates a full static HTML website based on raw data and a set of templates. Essentially, a static site generator automates the task of coding individual HTML pages and gets those pages ready to serve to users ahead of time. Because these HTML pages are pre-built, they can load very quickly in users’ browsers.

Eleventy (11ty)

A simpler static site generator. An alternative to Jekyll. Written in JavaScript. Transforms a directory of templates (of varying types) into HTML.

Works with HTML, Markdown, Liquid, Nunjucks, Handlebars, Mustache, EJS, Haml, Pug, and JavaScript Template Literals.

Features

  • Easy to set-up
  • Supports multiple Templates languages (Nunjucks, HTML, Javascript, Markdown, Liquid)
  • Customizable

Eleventy v0.12.1 requires Node 10 or newer

Steps to build a simple eleventy site

1: CREATE A PACKAGE.JSON

Installing Eleventy into our project requires a package.json file.

2: INSTALL ELEVENTY INTO PACKAGE.JSON

Now we can install and save Eleventy into our project’s package.json by running:

3: RUN ELEVENTY

We can use npx to run our local project version’s version of Eleventy. Let’s make sure our installation went okay and try to run Eleventy:

4: CREATE SOME TEMPLATES

Let’s run two commands to create two new template files (A Html and Markdown file)

This will compile any content templates in the current directory or subdirectories into the output folder (defaults to _site).

Run eleventy --serve to start up a web server. Then open http://localhost:8080/README/ in your web browser of choice to see your Eleventy output.

A software engineer with considerable experience in mobile development, native Android, and IOS development(Xcode), flutter dev, technical writing and community