Building a technical documentation static site for open source projects
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.
npm init -y2: INSTALL ELEVENTY INTO PACKAGE.JSON
Now we can install and save Eleventy into our project’s package.json by running:
npm install - save-dev @11ty/eleventy3: 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:
npx @11ty/eleventy4: CREATE SOME TEMPLATES
Let’s run two commands to create two new template files (A Html and Markdown file)
echo '<!doctype html><html><head><title>Page title</title></head><body><p>Hi</p></body></html>'echo '# Page header'
This will compile any content templates in the current directory or subdirectories into the output folder (defaults to _site).
npx @11ty/eleventy - serveRun 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.
