The Hugo boilerplate we use for our projects.
Disclaimer - This boilerplate has been heavily integrated with Netlify, and therefore many features are specific to the Netlify platform and may not work with other hosting providers.
Disclaimer - Atlas is a boilerplate (starter kit) for bespoke Hugo projects. It's not a Hugo theme and cannot be placed inside the /themes directory. Check the theme docs for more information.
Atlas provides the following features out of the box:
- A set of Gulp tasks for SASS, Linting, ES2015, Image compression
- Environment driven
robots.txtfile (disallows robots on everything other than production) - Base HTML templates with easy customisation/extension
- Configuration for Netlify deployments
- Better defaults for configuring HTTPS
- Better redirects with Netlify instead of
<meta http-equiv="refresh">
Atlas does not include a copy of the hugo binary. You will need to install Hugo first you can run any of the commands mentioned below.
To get started, you can either clone the repository, or deploy straight to Netlify. Then run the following from the project root:
npm install
npm run server
There are 3 commands available:
npm run build- Builds assets (sass, js, fonts, images) and runshugonpm run build:preview- The same asbuild, but runshugo --buildDrafts --buildFuturenpm run server- Runs BrowserSync and watches for changes, runningbuildwhen changes are detected
A default robots.txt can be found at /layouts/robots.txt which is configured to disallow crawlers when the HUGO_ENV environment variable is not set to "production".
The default behaviour is to disallow search engines on "branch" deployments. If you're using split testing, you will need to modify the default robots.txt template to ensure your branch deployments can be indexed.
Atlas has netlify-lambda installed out of the box to make working with Netlify Functions that much easier. Functions should be made inside src/lambda and should end in the .js extension. They will be compiled into /functions where Netlify will recognise them and deploy them automatically.
Here is an example that you can start from:
exports.handler = (event, context, callback) => {
callback(null, {
statusCode: 200,
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: "Hi from Lambda."
})
});
}
Headers can be configured within /layouts/index.headers, which is then built to /public/_headers.
This is a Netlify feature. Learn more about Headers with Netlify.
Atlas comes with some default headers to help you better protect your site. The default headers we include are: X-Frame-Options, X-XSS-Protection, X-Content-Type-Options, Referrer-Policy.
These headers are configured with the following values:
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: origin-when-cross-origin
Redirect rules can be appended to /layouts/index.redirects, which is then built to /public/_redirects.
This is a Netlify feature. Learn more about Netlify Redirects.
Hugo Aliases are usually handled by <meta http-equiv="refresh" ...> tags. These have been disabled within config.toml with disableAliases = true, and instead are handled by Netlify Redirects. This is handled automatically and you should continue to add aliases as described in the Hugo documentation.
Atlas provides a copy of Netlify CMS which is a fantastic CMS for JAMstack sites where everything is managed by GIT.
You will need to configure Netlify CMS to point to your own repo. You can do this within /static/admin/config.yml by updating backend: repo: with your repository information. Here's an example:
backend:
name: github
repo: indigotree/atlas
Checkout the quick start section on the Netlify CMS docs for more information.
If Netlify CMS isn't your thing, you can remove it with:
npm run cms:delete
Atlas is a boilerplate (starter kit) designed to aid bespoke Hugo development. Using existing themes with Atlas is possible, but unsupported.
Atlas files will take priority over your theme due to the order Hugo looks for files. For this reason, you will have to remove most of the files inside /layouts with the exception of _headers, _redirects and robots.txt.
If you wish the develop your site as a theme inside Atlas, you can copy /layouts into your theme and update the references within the gulpfile.babel.js.
│
└──── /layouts - Template files
│ │ 404.html - 404 Template
│ │ index.headers - Custom Netlify HTTP headers
│ │ index.redirects - Custom Netlify redirect rules
│ │ robots.txt - Template for robots.txt
│ │
│ └──── /_default - Base templates for list & singular pages
│ │ │ baseof.html - Base template
│ │ │ list.html - List/taxonomy template
│ │ │ single.html - Singular page/post template
│ │
│ └──── /partials - Partials
│ │
│ └──── /site - Site partials loaded into _default/baseof.html template
│ │ meta.html - Site <meta> tags
│ │ header.html - Sites primary <header>
│ │ footer.html - Sites primary <footer>
│ │ scripts.html - JavaScript <script> referenced before closing </body>
│ │ styles.html - Stylesheets referenced before closing </head>
│ │
| └──── /src - Source files for assets (SASS, JS, Images, Fonts etc)
│ │
│ └──── /static - Hugo static resources
│ │
│ └──── /admin - Netlify CMS templates
│
│ .gitignore
│ .sass-lint.yml - Linting rules for sass-lint
│ LICENSE
│ README.md
│ config.toml - Hugo configuration
│ gulpfile.babel.js - Gulp configuration/tasks
│ netlify.toml - Netlify configuration
│ package.json
You can deploy directly to Netlify using this button:
MIT © Indigo Tree