lockedata/user_hugo_template

template site for useR conferences organised by R Consoritum and partners

useR! website

What I can do

I can give you most of a website for useR! events, ready (almost) out of the box. I have a number of sections to help you out:

• Title Page with:
  • Overview/ About section supporting Markdown
  • Important Dates table
  • Twitter feed section
  • Organizing and Programming committee bios
  • Recent News section, supporting markdown blogging
  • Sponsors section
  • Social links in the footer
• Pages supporting Markdown for:
  • Program
  • Participation (ticket registration and paper submission)
  • Venue information (with google maps)
  • News section with all blog posts
  • FAQ
  • Contact section with contact form
  • Code of Conduct Section
  • About

What I am

I am a Hugo website, with two themes. Universal provides the base layer of theming, with a custom useR theme which overides some areas of Universal. The folder themes/[theme]/layout/partials/ contain all the .html needed for the website pages, with the exception of the Markdown, which is saved in /content/.

How to set me up on GitLab

This part will be done for you by a member of the RFCC.

Create a new repository

1. Log on to the R-conferences GitLab.

2. Create a new repository for the year the site will be for. E.g. https://gitlab.com/R-conferences/user[YEAR].git

Set the repo as a mirror of the main repository

1. In a terminal with access to git, navigate to a directory where you will clone the repository.

2. Create a bare clone of the repository.

   git clone --bare https://github.com/lockedata/user_hugo_template
   

3. Mirror-push to the new repository.

   cd user_hugo_template.git
   git push --mirror https://gitlab.com/R-conferences/user[YEAR].git
   

   Note, if you get the error

   remote: HTTP Basic: Access denied
   

   you may need to run the following command first

   git config --system --unset credential.helper
   

   (if using the Windows command prompt you will need to be running as Administrator).

4. Remove the temporary local repository you created in step 1.

   cd ..
   rm -rf user_hugo_template.git
   

Deploy to Netlify

1. Login to Netlify via R-conferences GitLab account.
2. Click "New site from Git".
3. Select GitLab as the git provider.
4. Select the repository created in the previous steps.
5. Use the build command hugo.
6. Use the publish directory public .

How to set me up locally

This part should be done by anyone maintaining the website.

Clone the new repository

1. Clone the new repository set up at https://gitlab.com/R-conferences/user[YEAR].git.

Initialise the submodules

If you want to run the site locally to view when you're making changes, you need to initialise the submodules

1. Open a terminal with access to git.
2. Navigate to the new repo.
3. Initialise and fetch the submodules.

   git submodule init
   git submodule update
   

Customise the config

The file config.toml gives you access to a number of points on the site, mostly using site params.

A high level overview of these features:

• enable
  • boolean to render or hide that section
• title/subtitle/description/button text/...
  • strings to display text in that position
• bg
  • boolean to toggle lightly shaded backgrounds on or off for that section
• photo1/photo2
  • toggle between background-image-fixed-1/background-image-fixed-2 as a background, which are located in static/img/

Bios

The team bios are constructed from the [[params.programming.members]] and [[params.organising.members]]. Most of these fields are optional and can be deleted to prevent them rendering in the site.

The icons can be changed per person with FontAwesome.

The headshots are held in static/img/organising and static/img/programming. The 'faceholder' is in /themes/hugo-user-theme/static/img/[organising and programming], but you should place yours in the root /static/img/[organising and programming], which will mask/override the blanks.

Sponsors

Sponsor images should be held in static/img/sponsors. The files in /data/sponsors/ control the how and what sponsor image is displayed, and it's location in a folder tier1, tier2, and tier3 control where it is on the page.

Important Dates

Is sourced from a csv stored in /csv.

Content pages

Markdown files are located in /content. The News/blog is driven from /content/blog, and the other pages in the navbar are driven from the files in /content/. An example of how subpages could be constructed is located in this commit where the shared 'parent' of 2 content.md are specified in the config.

What if I need even more customistation?

In the hopefully rare event that even more specific material is needed you can explore the following. Make use of the hugo inheritance method to override defaults where applicable, rather than modify the defaults in place.

CSS/style

• Copy the base hugo-user-theme/static/css/styledefault.css into /static/css/style.css in your root
  • This will now be the style sheet for your website, overriding the themes

New Section/Custom Section

• Either
  • find a partial from /layouts/partials in the existing themes you want to base your work on, copy it to the project /layouts/partials, and modify the copy
  • write a new myfile.html from scratch and include it in the project /layouts/partials
• then make sure that it is referenced in index.html

Deployment

The website created for you by the RFCC will be automatically updated when you push your changes to the master branch.

user_hugo_template's Issues

Hugo is "unable to locate layout" for pages.

Have cloned this repo and got the git submodules. Running hugo on the repo files as supplied does not generate the HTML in the public folder. Should it?

Running hugo -v shows a whole load of similar "Unable to locate" warnings ending with:

WARN 2019/03/25 14:40:01 [en] Unable to locate layout for "home": [page/index.en.html.html theme/page/index.en.html.html page/home.en.html.html theme/page/home.en.html.html page/list.en.html.html theme/page/list.en.html.html page/index.html.html theme/page/index.html.html page/home.html.html theme/page/home.html.html page/list.html.html theme/page/list.html.html page/index.en.html theme/page/index.en.html page/home.en.html theme/page/home.en.html page/list.en.html theme/page/list.en.html page/index.html theme/page/index.html page/home.html theme/page/home.html page/list.html theme/page/list.html index.en.html.html theme/index.en.html.html home.en.html.html theme/home.en.html.html list.en.html.html theme/list.en.html.html index.html.html theme/index.html.html home.html.html theme/home.html.html list.html.html theme/list.html.html index.en.html theme/index.en.html home.en.html theme/home.en.html list.en.html theme/list.en.html index.html theme/index.html home.html theme/home.html list.html theme/list.html _default/index.en.html.html theme/_default/index.en.html.html _default/home.en.html.html theme/_default/home.en.html.html _default/list.en.html.html theme/_default/list.en.html.html _default/index.html.html theme/_default/index.html.html _default/home.html.html theme/_default/home.html.html _default/list.html.html theme/_default/list.html.html _default/index.en.html theme/_default/index.en.html _default/home.en.html theme/_default/home.en.html _default/list.en.html theme/_default/list.en.html _default/index.html theme/_default/index.html _default/home.html theme/_default/home.html _default/list.html theme/_default/list.html]
WARN 2019/03/25 14:44:25 [en] Unable to locate layout for "404": [404.html]
                   | EN  
+------------------+----+
  Pages            | 14  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     | 20  
  Processed images |  0  
  Aliases          |  0  
  Sitemaps         |  1  
  Cleaned          |  0  

There's no HTML generated in public, only the static and sitemap files:

$ ls public/
categories  img  index.xml  news  sitemap.xml  tags

I'm not a hugo expert. Does this need a different version? I'm on:

$ hugo version
Hugo Static Site Generator v0.40.1 linux/amd64 BuildDate: 2018-04-25T17:16:11Z

which is recent.