2016-08-09 23:42:05 +00:00
# Victor Hugo
2016-07-05 18:38:18 +00:00
2017-10-10 17:24:15 +00:00
**A Hugo boilerplate for creating truly epic websites**
2016-08-09 23:42:05 +00:00
2018-12-03 21:44:11 +00:00
This is a boilerplate for using [Hugo ](https://gohugo.io/ ) as a static site generator and [Webpack ](https://webpack.js.org/ ) as your asset pipeline.
2016-07-05 18:38:18 +00:00
2017-10-10 17:24:15 +00:00
Victor Hugo setup to use [PostCSS ](http://postcss.org/ ) and [Babel ](https://babeljs.io/ ) for CSS and JavaScript compiling/transpiling.
2016-07-05 18:38:18 +00:00
2016-09-21 17:37:14 +00:00
This project is released under the [MIT license ](LICENSE ). Please make sure you understand its implications and guarantees.
2016-07-05 18:38:18 +00:00
## Usage
2018-10-23 16:35:37 +00:00
### :exclamation: Prerequisites
2017-01-19 22:13:59 +00:00
2017-10-10 17:24:15 +00:00
You need to have the latest/LTS [node ](https://nodejs.org/en/download/ ) and [npm ](https://www.npmjs.com/get-npm ) versions installed in order to use Victor Hugo.
Next step, clone this repository and run:
2016-07-05 18:38:18 +00:00
```bash
npm install
2017-10-10 17:24:15 +00:00
```
2018-04-27 14:04:50 +00:00
This will take some time and will install all packages necessary to run Victor Hugo and its tasks.
2017-10-10 17:24:15 +00:00
2018-10-23 16:35:37 +00:00
### :construction_worker: Development
2017-10-10 17:24:15 +00:00
While developing your website, use:
```bash
2016-07-05 18:38:18 +00:00
npm start
```
2018-05-14 14:16:17 +00:00
or for developing your website with `hugo server --buildDrafts --buildFuture` , use:
```bash
2018-12-03 21:44:11 +00:00
npm run preview
2018-05-14 14:16:17 +00:00
```
2018-12-03 21:44:11 +00:00
Then visit http://localhost:3000/ _- or a new browser windows popped-up already -_ to preview your new website. Webpack Dev Server will automatically reload the CSS or refresh the whole page, when stylesheets or content changes.
2017-10-10 17:24:15 +00:00
2018-10-23 16:35:37 +00:00
### :package: Static build
2017-10-10 17:24:15 +00:00
To build a static version of the website inside the `/dist` folder, run:
2016-07-05 18:38:18 +00:00
```bash
npm run build
```
2017-10-10 17:24:15 +00:00
To get a preview of posts or articles not yet published, run:
```bash
2018-12-03 21:44:11 +00:00
npm run build:preview
2017-10-10 17:24:15 +00:00
```
2018-12-03 21:44:11 +00:00
See [package.json ](package.json#L8 ) for all tasks.
2017-10-10 17:24:15 +00:00
2016-08-09 22:38:45 +00:00
## Structure
```
|--site // Everything in here will be built with hugo
| |--content // Pages and collections - ask if you need extra pages
| |--data // YAML data files with any data for use in examples
| |--layouts // This is where all templates go
| | |--partials // This is where includes live
| | |--index.html // The index page
| |--static // Files in here ends up in the public folder
|--src // Files that will pass through the asset pipeline
2018-12-03 21:44:11 +00:00
| |--css // Webpack will bundle imported css seperately
| |--index.js // index.js is the webpack entry for your css & js assets
2016-08-09 22:38:45 +00:00
```
## Basic Concepts
You can read more about Hugo's template language in their documentation here:
https://gohugo.io/templates/overview/
The most useful page there is the one about the available functions:
https://gohugo.io/templates/functions/
For assets that are completely static and don't need to go through the asset pipeline,
use the `site/static` folder. Images, font-files, etc, all go there.
2018-04-27 14:04:50 +00:00
Files in the static folder end up in the web root. So a file called `site/static/favicon.ico`
2016-08-09 22:38:45 +00:00
will end up being available as `/favicon.ico` and so on...
2018-12-03 21:44:11 +00:00
The `src/index.js` file is the entrypoint for webpack and will be built to `/dist/main.js`
2016-08-09 22:38:45 +00:00
2017-10-10 17:24:15 +00:00
You can use **ES6** and use both relative imports or import libraries from npm.
2016-08-09 22:38:45 +00:00
2018-12-03 21:44:11 +00:00
Any CSS file imported into the `index.js` will be run through Webpack, compiled with [PostCSS Next ](http://cssnext.io/ ), and
minified to `/dist/[name].[hash:5].css` . Import statements will be resolved as part of the build.
2016-08-09 22:38:45 +00:00
2017-08-10 14:34:17 +00:00
## Environment variables
2018-12-03 21:44:11 +00:00
To separate the development and production _- aka build -_ stages, all gulp tasks run with a node environment variable named either `development` or `production` .
2017-10-06 23:02:24 +00:00
2017-10-10 17:24:15 +00:00
You can access the environment variable inside the theme files with `getenv "NODE_ENV"` . See the following example for a conditional statement:
2017-08-10 14:34:17 +00:00
{{ if eq (getenv "NODE_ENV") "development" }}You're in development!{{ end }}
2018-12-03 21:44:11 +00:00
All tasks starting with _build_ set the environment variable to `production` - the other will set it to `development` .
2017-08-10 14:34:17 +00:00
2017-10-10 17:24:15 +00:00
## Deploying to Netlify
2016-07-05 18:38:18 +00:00
2016-08-10 00:06:10 +00:00
- Push your clone to your own GitHub repository.
- [Create a new site on Netlify ](https://app.netlify.com/start ) and link the repository.
2016-07-05 18:38:18 +00:00
2017-10-10 17:24:15 +00:00
Now Netlify will build and deploy your site whenever you push to git.
2016-08-09 22:38:45 +00:00
2016-12-14 21:42:05 +00:00
You can also click this button:
2017-09-04 21:20:36 +00:00
[![Deploy to Netlify ](https://www.netlify.com/img/deploy/button.svg )](https://app.netlify.com/start/deploy?repository=https://github.com/netlify/victor-hugo)
2016-12-14 21:42:05 +00:00
2017-10-10 17:24:15 +00:00
## Enjoy!! 😸