Project site isn’t only a marketing tool — it also allows you to show your project to its potential users and give them the opportunity to try the project in their browsers.
For many projects GitHub repository would be enough but Markdown pages are the only tool you have there, and a site have some advantages, like easier navigation, interactive examples and demos, or better documentation search.
Design for Hackers email course and Hello Web Design book are good resources to improve your design skills. And the Beautiful Open gallery is good if you need some inspiration.
There are countless number of tools to make a site — look at the list of top static generators, for example. You can handcode your site or write your own engine, like authors of this book did, though we don’t recommend that unless your needs are unusual.
Many open source projects’ sites are built with the JAMstack: static HTML, generated from Markdown content, and, possibly, data from different APIs. It’s convenient because you don’t need any backend or a database and can use any hosting, and some of them are free for open source projects.
Docusaurus is static site generator that was made for open source sites. It’s React-based, supports localizations, versioning, blog and has Algolia documentation search integration.
It will create a basic configuration for Docusaurus in website and folders with example documentation and a blog. The website has its own package.json and npm scripts to run and build your new site.
Then tweak example files to your needs:
Now you can run a dev server:
cd website npm run start
http://localhost:3000 in your browser:
Even with minimal setup you can create a good-looking site. And later you can customize styles and layout as you like.
Jekyll is a popular Ruby-based static site generator.
If you’re using GitHub Pages you don’t need to install anything. You can even edit code in GitHub web UI and your site will be updated automatically.
Gatsby is a React-based static site generator. It’s used by popular projects like React and Storybook. You’ll get a nice developer experience with hot reload and a fast site: Gatsby generates a static progressive web app, so it loads only critical resources for the first page, but later prefetches resources for other pages and works as single page app without rull page reload.
GitBook is a tool that generates ebooks from Markdown content. Ebooks are the main use case of GitBook, but the HTML version can work well as a documentation site. It has a nice default theme and search that works without any backend.
Redux site is a good example:
You can use tools, described in the API Documentation chapter, to create a site. Most of these tools allow you to add additional Markdown files with some introductory information. You can customize theme for your liking or you can generate Markdown files and use them as source for your Jekyll or Gatsby site.
If your project can work in a browser, it’s a great opportunity to show it in action on your site.
REPLs, which stands for Read–eval–print loop, allow your visitors to play with a tool in a browser: edit code or change options — and immediately see the results. Prettier and Babel have good examples.
CodeSandbox allows you to create a REPL for a whole project with many files, webpack and dependencies.
GitHub Pages is a free hosting for open source projects. You can host static HTML or a site powered by Jekyll.
You can host a site for your GitHub user, organization or a project. GitHub Pages have a dozen of themes that you can use if your design skills are not great:
Netlify is a static hosting with global CDN, HTTPS and continuous deployment. They provide one of their paid plans for free for open source projects.
If you’re using Jekyll and GitHub pages, you don’t need to do anything — push your changes to the repository, and GitHub will do the rest.
If you have to generate HTML pages before publishing, you will not want to store them in the main repository of your project. Instead you can use a branch or a separate repository.
Use gh-pages command line tool to commit generated files to another branch (like
gh-pages for GitHub Pages).
Or you can store your site code in a separate repository, use a web hook to trigger a script that will download Markdown documentation from your project’s main repository and build a site on every commit to the main repository.
#!/usr/bin/env bash set -e # URL to download the main project repository REPO_TAR_GZ="https://codeload.github.com/styleguidist/react-styleguidist/tar.gz/master" # Download and unpack the main repository curl "$REPO_TAR_GZ" | tar xz # Build the site # It should use Markdown files from downloaded react-styleguidist folder npm run build
Free domain names by hosting providers are usually long, like
username.github.io or even
You can buy a custom domain (like
projectname.com) or use a free one from js.org.
If your site content is in Markdown, look at the Linting and Formatting chapter.
Mot likely you don’t need many tests for your site unless you’re doing something complicated, like a custom REPL. But one type of tests maybe useful: deployment smoke test.
To create a basic smoke test you can write a shell script that will download a home page of your site and check that some text is present there, so you’ll know that your site isn’t completely broken.
#!/usr/bin/env bash set -e # Deployment... # Smoke test curl --silent https://react-styleguidist.js.org | grep --silent "Development environment" || (echo "Smoke test failed" && exit 1)
The subject is so broad that we could write a separate book only about sites for open source projects. The purpose of this chapter is to give you some ideas for your own research.
Site of an open source project is an open source project in itself: don’t forget to add an Edit link on each page, so people could contribute improvements.