community-project-boilerplate

Note: this boilerplate is outdated, and should be reviewed before used. There are critical vulnerabilites in the dependencies used for building the site.

Table of Contents generated with DocToc

• What is it
• Requirements
• Initial setup
• Publish docs to https://community.algolia.com/my-project
• Local development
• Test build
• Changes to be done before going live
• Project structure
• Assets and links references
• Deploy previews
• Contributing

What is it

A simple community boilerplate to replicate Algolia websites like InstantSearch*.

Requirements

To run this project, you will need:

• Node.js >= v9.2.0, use nvm - install instructions
• Yarn >= v1.3.2 - install instructions

Initial setup

git clone git@github.com:algolia/community-project-boilerplate.git my-project
cd my-project
nvm use
rm -rf .git
git init
git remote add origin git@github.com:algolia/my-project.git
yarn
yarn docs:update
git add docs README.md CONTRIBUTING.md
git commit -m 'first commit'
git push

Publish docs to https://community.algolia.com/my-project

You need to activate GitHub pages for your repository (in settings on GitHub), choose "master branch /docs folder".

Every time you want to update your production website, do:

yarn docs:update
git add docs README.md CONTRIBUTING.md
git commit -m 'docs(update): something'
git push

At some point this will be moved to Netlify.

Local development

yarn
yarn start

Go to https://localhost:3000. There should be auto reload for almost everything, but when it fails just restart the server.

Test build

This will run the build of the website and serve it. Useful when you are modifying production middlewares and want to ensure the resulting website will be working. Like when adding CSS minification.

yarn docs:test-build

Changes to be done before going live

• Rename any folder and replace any occurence of community-project-boilerplate to my-project.
• Remove meta(name='ROBOTS', content='NOINDEX, NOFOLLOW') from src/community-project-boilerplate-docgen/layouts/common/meta.pug.

Project structure

• Pages (index, about..) are in src/community-project-boilerplate-docgen/src
• Layouts are in src/community-project-boilerplate-docgen/layouts
• JS and images are in src/community-project-boilerplate-docgen/assets
• Stylesheets are in src/community-project-boilerplate-docgen/src/stylesheets

Assets and links references

To reference assets and links from any HTML page in this website, always reference them from the root of the website, without any leading "." or "/". Links from HTML pages are always relative to the root of your website, not the current file.

To ease hosting on different subpaths (https://community.algolia.com/website/ and http://localhost:3000/), we use a <base href> tag that allow us to easily achieve that.

If your image is in assets/images/image.png then you can reference it in your HTML page like that: <img src="assets/images/image.png" /> and it will always work no matter how the website is hosted.

Same for linking to a particular page, if you are in index.html (or index.md), to link to about/team.html just do this: <a href="about/team.html">team</a>.

For ressources inside CSS files, always use relative paths from the CSS file itself like background-image: url("../assets/image/image.png"));

Deploy previews

.

If you want to have deploy previews, which are live deployments of your website from pull requests submitted to this repository, please:

• Go to https://www.netlify.com/
• Login with GitHub
• Add "New site from Git"
• Leave everything by default
• Go to your Netlify project, click on Deploys > Notifications
• Open a new tab Login to GitHub on a bot like account (algobot for Algolia)
• Return to Netlify, add a notification as a GitHub comment
• Choose "Deploy succeeded"
• Click on "generate access token in GitHub"

Now the bot you logged in will generate a dedicated token for this project and will be the author of the comments when something new is deployed.

You can now logout from GitHub and login again with your real account.

Contributing

See CONTRIBUTING.