A static website generator is a software that generates a full, static HTML web site based mostly on uncooked knowledge and a set of templates. It automates the duty of coding particular person HTML pages and will get these pages able to serve to customers. Because the HTML pages are prebuilt, they load in a short time in customers’ browsers.
Static websites work notably effectively for documentation, too, as a result of static websites are straightforward to scale, and so they’re a straightforward solution to generate, keep, and deploy your mission’s documentation. For these causes, organizations typically use them to doc utility programming interfaces (APIs), database schemas, and different info. Documentation is a crucial a part of software program growth, design, and different features of tech. All codebases require some type of documentation, with choices starting from a easy README to full documentation.
Eleventy: A static website generator
Eleventy (11ty) is an easy static website generator and a substitute for Jekyll and Hugo. It’s written in JavaScript and transforms a listing of templates (of various varieties) into HTML. It’s additionally open supply, launched below the MIT License.
Eleventy works with HTML, Markdown, Liquid, Nunjucks, Handlebars, Mustache, EJS, Haml, Pug, and JavaScript Template Literals.
Its options embody:
- Easy setup
- Supports a number of template languages (e.g., Nunjucks, HTML, JavaScript, Markdown, Liquid)
- Customizable
- Based on JavaScript, which is acquainted to many internet builders and straightforward for brand spanking new customers to be taught
Install Eleventy
Eleventy requires Node.js. On Linux, you possibly can set up Node.js utilizing your package deal supervisor:
$ sudo dnf set up nodejsIf your package deal supervisor does not have Node.js accessible, or if you happen to’re not on Linux, you possibly can install it from the Node.js web site.
Once Node.js is put in, use it to put in Eleventy:
$ npm set up -g @11ty/eleventyThat’s it!
Build a static website in your documentation
Now you can begin utilizing Eleventy to construct your static documentation website. Here are the steps to observe.
1. Create a package deal.json file
To set up Eleventy into your mission, you want a package deal.json file:
$ npm init -y2. Install Eleventy into package deal.json
Install and save Eleventy into your mission’s package deal.json by operating:
$ npm install-save-dev @11ty/eleventythree. Run Eleventy
Use the npx command to run your native mission’s model of Eleventy. After you confirm set up went as anticipated, attempt to run Eleventy:
$ npx @11ty/eleventyfour. Create some templates
Now run two instructions to create two new template information (an HTML and a Markdown file):
$ cat << EOF >> index.html
<!doctype html><html>
<head>
<title>Page title</title>
</head><physique>
<p>Hello world</p>
</physique></html>
EOF
$ echo '# Page header' > index.md
This compiles any content material templates within the present listing or subdirectories into the output folder (which defaults to _site).
Run eleventy --serve to begin a growth internet server.
$ npx @11ty/eleventy-serveOpen http://localhost:8080/README/ within the internet browser of your option to see your Eleventy output.
Then add the information in _site to your internet server to publish your website for the world to see.
Try Eleventy
Eleventy is a static website generator that is straightforward to make use of, template, and theme. If you are already utilizing Node.js in your growth workflow, Eleventy could also be a extra pure match than Jekyll or Hugo. It supplies nice outcomes shortly and saves you from complicated website design and upkeep. To be taught extra about utilizing Eleventy, learn by its documentation.
This relies on Building a technical documentation static site for open source projects, which first appeared on Nwokocha Wisdom Maduabuchi’s Medium website, and is republished with permission.