# Setup from scratch

How to set up a new docs site in a repo.

We hope to make it much easier to set up a new docs site soon, but in the meanwhile you might want to ask someone who’s done it before. Here’s the full documentation for how to do it.

## Add files to the repo

Maybe get a coffee first.

1. Go to the folder where you want the docs. For example, you might want this to be inside docs inside your repo.

2. Make directories called /source, /themes, /assets, and /public

3. Copy in /assets/theme-colors.less with the following content:

4. Add the theme as a submodule.

5. Add a .gitignore:

6. Create a _config.yml, copy and adapt it. Here are the most important fields:

1. sidebar_categories defines the sidebar, and the order of the pages. This has to be correct for the site to work at all.
2. github_repo should be the name of your repo, like apollographql/apollo-link
3. content_root should be the path to the directory where your actual source markdown is, like docs/source
4. url should be the complete url, like https://www.apollographql.com/docs/link/
5. root should be the part after the domain, like /docs/link/
6. public_dir should be like root but with public, like public/docs/link
7. Create a public/_redirects file, which is just one line. This makes Netlify deploy previews easier to use since we aren’t hosting the sites at the root of the domain.

8. Copy in a package.json: https://github.com/apollographql/community/blob/master/package.json

9. Test it. Good luck!

1. npm install inside the docs directory (commit package-lock.json)
2. npm start to run the site (this should be a package script that has hexo serve in it)

### Common errors

This means that the “page” is undefined, which means it can’t find something in your sidebar_categories. Check if you have a page listed there which doesn’t exist in your source directory.

## Deploying to Netlify

We try to use netlify for our deploys because it gives you nice deploy previews on PRs, and makes it super easy to set up HTTPS.

1. Push to GitHub
2. Go to https://app.netlify.com/teams/meteor/sites. If you’re not on the Netlify team called “meteor”, get someone to invite you. (this process will still work if you’re not in the team, but it will be harder for others to manage the site)
3. Click “new site from git” and create a new site with the repository you pushed to
4. In build settings, put:
1. If your site is at the root:
1. Build command: npm run build
2. Publish directory: public
2. If your docs are in a subdir like docs, instead do:
1. Build command: cd docs && npm i && npm run build
2. Publish directory: docs/public
5. Don’t forget to add the “meteor” team
6. Hit deploy!
7. Set a nice name for the site, instead of the auto-generated one.

This is for paths that are under https://www.apollographql.com.

1. Go to https://fly.io/sites/www-apollodata-com/backends
2. If you’re not on the fly.io “meteor” team, ask someone to add you