git clone git@github.com:algolia/jekyll-algolia.git my-project
cd my-project
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 jekyll-algolia to my-project.
Remove meta(name='ROBOTS', content='NOINDEX, NOFOLLOW') from src/jekyll-algolia-docgen/layouts/common/meta.pug.

Project structure

Pages (index, about..) are in src/jekyll-algolia-docgen/src
Layouts are in src/jekyll-algolia-docgen/layouts
JS and images are in src/jekyll-algolia-docgen/assets
Stylesheets are in src/jekyll-algolia-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"));

Contributing

See CONTRIBUTING.