Hugo and Webpack

started.md

Creating Your Environment

Basic Neccesities

• Github: https://github.com/UX-Society
• Github Education: https://education.github.com/pack
• Webstorm: https://www.jetbrains.com/webstorm/
• fish (recommended): https://fishshell.com/

Setup

Make a GitHub account and add UX-Society repository linked and fork the NSU-website to edit it. Then use the Github Education link to get free stuff. Do the same to get Webstorm for free (or use an IDE of your choice). Fish is a recommended shell to replace bash and will make terminal work easier, but is not required.

Basic Terminal Usage

The terminal is a powerful way to use a computer and learning how to use it properly important for serious work. Using the terminal is easy for macOs and other Linux based computers and replacing bash with fish will make it even easier. (idk about windows). To use the terminal a command has to be given which follows this general format.

    "command name" "command sub-name" -arguments "info"

For example:

    sudo apt-get install -y fish

To break this command down, it starts with 'sudo' which indicated that the command is being run with max user authorization, use it very carefully. 'apt-get' is the main command and it tells the computer that I want to manage my packages (package is a name for a software bundle, which has been replacing by App). 'install' tells the computer that I want to install a package, a feature of apt-get. '-y' is an argument denoted by the dash and slightly changes what the computer does, in this case, to automatically skip the installation confirmation dialogue. 'fish' is the info of what is being done, in this case, the package.

Here are some useful commands:

• cd: 'change directory' - it moves you around the filesystem. Ex: cd WebstormProjects/nsu-website/
• ls: 'list directory contents' - tells you all the files in the current dir. Ex: ls -a
• man: 'manual' - tells you how to use a command. Ex: man man (tells you how to use itself)

Libraries and Tools

• Webpack: https://webpack.js.org/
• Hugo: https://gohugo.io/
• Sass: http://sass-lang.com/guide
• Yarn or npm: https://yarnpkg.com/en/ or https://www.npmjs.com/

Installing

This project requires yarn and Hugo. Hugo is used to building the site and view a demo of what the site will look like. The yarn is used to install the node packages such as webpack and lint. These tools help streamline the javascript and CSS.

Getting Started

Building The Static Stuff

package.json has been configured with some helpers to simplify the build process for building the javascript and the scss files. These commands will only work under a director with a package.json file.

• yarn run build' or 'npm run build
  • will build from src to public
• yarn run watch or npm run watch
  • will build and watch for changes in src, but the webpack build has to be running for these changes to update

Building the CSS and javascript will take in the contents of src and output it to the public. Look in the package.json file under scripts to see where the run commands wire to. for instance yarn run lint will run eslint on the codebase.

  "scripts": {
    "lint": "eslint .",
    "install_hugo": "brew update && brew install hugo",
    "build": "webpack",
    "watch": "webpack --watch"
  },

To actually preview the site run Hugo server from the root or the project folder (cd WebstormProjects/nsu-website/). This folder should contain a themes folder. If everything runs correctly this should output to the terminal:

WARNING: calling IsSet with unsupported type "invalid" (<nil>) will always return false.


The built site for language en:
0 draft content
0 future content
0 expired content
7 regular pages created
30 other pages created
0 non-page files copied
12 paginator pages created
7 tags created
4 categories created
total in 35 ms
Watching for changes in /home/michaelpollind/project/nsu-website/{data,content,static,themes}
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

note: you will need to run both the yarn and Hugo commands. To do this open another tab in your current terminal or a new terminal. yarn will update the CSS and Hugo should react to the changes from webpack.

Usage

After running Hugo and yarn, view the site by going to http://localhost:1313/. Most of the files in the site can be ignored, the important files and directories to use are laid out here.

• /themes/source-flask-theme/ is the main folder of interest
  • /themes/config.toml/ is where the actual info for the site is linked (titles, text, images). Edit your section under [params."your section name] and reference this content with .Site.Params.morea_about."content name" in the html partial file
  • /themes/source-flask-theme/layouts/partials/ is were your section of html to edit will be found
  • /themes/source-flask-theme/src/sass/section/ is where your sass (css) file will be found
• /static/img/ is where images should be added

Edit these files to change the website locally and will be merged with the main branch when done. Html changes the elements and sass (CSS) changes the layout and appearance of those elements.