hugo-theme-introduction/README.md

204 lines
7.4 KiB
Markdown
Raw Normal View History

2018-07-18 15:39:54 +00:00
# Introduction theme for Hugo
2019-10-01 14:26:30 +00:00
[![Netlify Status](https://api.netlify.com/api/v1/badges/51d09485-c9d1-4a88-90ba-894f09e5a29d/deploy-status)](https://app.netlify.com/sites/hugo-introduction/deploys)
![Test Hugo versions](https://github.com/victoriadrake/hugo-theme-introduction/workflows/test-versions/badge.svg)
2019-07-24 23:51:35 +00:00
![Latest Release](https://img.shields.io/github/tag/victoriadrake/hugo-theme-introduction.svg)
2017-03-13 09:14:02 +00:00
2018-09-03 07:49:47 +00:00
Introduction is a minimalist, highly-versatile theme for Hugo. It can be configured as a single page, or as a full-featured site with multiple sections. It is multilingual, responsive, and includes a light and dark theme.
2017-03-13 09:14:02 +00:00
![Device mockups](https://github.com/victoriadrake/hugo-theme-introduction/blob/master/images/mockup.png)
2017-03-13 09:45:32 +00:00
2017-03-13 09:14:02 +00:00
Features:
2018-09-03 07:49:47 +00:00
- Multilingual - supports side-by-side content in different language versions
- Custom index page sections from Markdown files
- Projects and Blog sections
- Page load fade-in CSS effect and smooth scrolling to anchor links
- Straightforward customization via `config.toml`
2020-05-31 18:12:41 +00:00
- Styled Markdown throughout, including post titles
- Syntax highlighting
2018-09-03 07:49:47 +00:00
Developer-friendly:
- Sass files included with instant compiling to CSS thanks to [Hugo Pipes](https://gohugo.io/hugo-pipes/postcss/) and [PostCSS](https://gohugo.io/hugo-pipes/postcss/)
- Thoughtful use of Sass variables makes creating new colour schemes easy
2018-09-03 07:49:47 +00:00
## Getting started
2020-02-14 16:56:25 +00:00
- Requires extended version of [Hugo](https://gohugo.io/getting-started/installing/) (latest version recommended)
To make changes to the theme CSS, extended Hugo's [PostCSS](https://gohugo.io/hugo-pipes/postcss/) requires JavaScript packages to compile the styles. You can install them using `npm`:
2020-06-21 17:53:54 +00:00
- [postcss-cli](https://github.com/postcss/postcss-cli): `npm install -g postcss-cli`
- [autoprefixer](https://github.com/postcss/autoprefixer): `npm install -g autoprefixer`
[Learn how to install and use npm here](https://www.npmjs.com/get-npm).
2018-09-03 07:49:47 +00:00
2019-08-07 09:18:07 +00:00
Note: If you are using [Hugo as a snap app](https://snapcraft.io/hugo), the above two Node.js packages have to be [installed locally inside `exampleSite`](https://gohugo.io/hugo-pipes/postcss/).
```sh
2019-08-07 09:18:07 +00:00
cd exampleSite/
npm install postcss-cli
npm install autoprefixer
2019-08-07 09:18:07 +00:00
```
2020-06-21 17:53:54 +00:00
If you see an error message like:
```text
Error: Error building site: POSTCSS: failed to transform "css/main.css" (text/css): resource "sass/sass/style..." not found in file cache
```
You may need to install these dependencies globally. See [issue #210](https://github.com/victoriadrake/hugo-theme-introduction/issues/210#issuecomment-645661326) for more information.
2018-09-03 07:49:47 +00:00
## Get the theme
2018-07-18 15:39:54 +00:00
Run from the root of your Hugo site:
2017-03-13 09:14:02 +00:00
```sh
git clone https://github.com/victoriadrake/hugo-theme-introduction.git themes/introduction
2017-03-13 09:14:02 +00:00
```
2019-12-29 03:27:19 +00:00
Alternatively, you can include this repository as a [git submodule](https://git-scm.com/docs/gitsubmodules). This makes it easier to update this theme if you have your Hugo site in git as well:
2018-07-18 15:39:54 +00:00
```sh
git submodule add https://github.com/victoriadrake/hugo-theme-introduction.git themes/introduction
2018-07-18 15:39:54 +00:00
```
2018-09-03 07:49:47 +00:00
## Preview the theme
Introduction ships with an fully configured example site. For a quick preview:
2017-03-13 09:14:02 +00:00
```sh
2020-02-14 16:56:25 +00:00
cd themes/introduction/exampleSite/
2018-09-03 07:49:47 +00:00
hugo serve --themesDir ../..
```
2017-03-13 09:14:02 +00:00
2018-09-03 07:49:47 +00:00
Then visit `http://localhost:1313/` in your browser to view the example site.
## Add content
2018-09-03 07:49:47 +00:00
The following explains how to add content to your Hugo site. You can find sample content in the `exampleSite/` folder.
## Introduction section
Create `index.md`:
```sh
2018-09-03 07:49:47 +00:00
hugo new home/index.md
```
The `title` frontmatter will be the first large heading.
2018-11-07 14:08:46 +00:00
The content of `index.md` will be shown as a subtitle line.
2018-09-03 07:49:47 +00:00
You might want to set `headless` to `true` in the frontmatter. See [headless bundles](https://gohugo.io/content-management/page-bundles/#headless-bundle) for more information.
## Home page
2018-11-07 14:08:46 +00:00
Content for the home page lives under `content/home/`. You may add as many files as you want to in markdown format.
2018-09-03 07:49:47 +00:00
Each markdown file will show as a section on the home page and can be ordered by the `weight` value in the file's frontmatter. You can set `image` to show an image on the left side of the section. The image file must be in the `content/home/` folder.
2017-03-13 09:14:02 +00:00
2018-07-26 23:33:44 +00:00
You may add a contact section by creating
2018-09-03 07:49:47 +00:00
`contact.md`:
```sh
2018-09-03 07:49:47 +00:00
hugo new home/contact.md
```
This will always be shown as the last section on the home page.
## Projects section
2018-11-07 14:08:46 +00:00
Introduction provides an easy way to showcase your projects. Each project can even have its own gallery, shown as an image carousel.
2018-09-03 07:49:47 +00:00
Start by creating an index file for the projects section:
2017-03-13 09:14:02 +00:00
```sh
2018-09-03 07:49:47 +00:00
hugo new projects/_index.md
```
Add a `title` and some optional content to the file.
Add an optional `weight` for ordering projects section.
2018-09-03 07:49:47 +00:00
To create a project, run:
```sh
2018-09-03 07:49:47 +00:00
hugo new projects/YourProjectName/index.md
```
2018-11-07 14:08:46 +00:00
The frontmatter of your new file contains some comments to help your configure your project.
2018-09-03 07:49:47 +00:00
You can set `external_link` to make the project link to another website.
Add images to your project by placing image files in the `YourProjectName/` folder. If you add more then one photo, they will display as a carousel gallery. Images will be ordered by filename. The first image will be shown as the project preview image. You can change the order of your images by adding a `weight` to that resource's parameters:
2017-03-13 09:14:02 +00:00
```sh
2018-07-26 23:33:44 +00:00
resources:
- src: NameOfYourImage.jpg
params:
weight: -100
2017-03-13 09:14:02 +00:00
```
2018-09-03 07:49:47 +00:00
## Blog section
2017-11-13 21:01:53 +00:00
2018-09-03 07:49:47 +00:00
Create an index file for the blog:
2017-11-13 21:01:53 +00:00
```sh
2018-09-03 07:49:47 +00:00
hugo new blog/_index.md
```
Add an optional `weight` for ordering blog section on your homepage
2017-11-13 21:01:53 +00:00
2018-09-03 07:49:47 +00:00
Create a new blog post with:
```sh
2018-09-03 07:49:47 +00:00
hugo new blog/YourEntryTitle.md
```
2017-11-13 21:01:53 +00:00
2018-09-03 07:49:47 +00:00
Posts will also display in the Blog section of the home page.
2017-11-13 21:01:53 +00:00
## Configure your site
2018-09-03 07:49:47 +00:00
From `exampleSite/`, copy `config.toml` to the root folder of your Hugo site and change the fields as you like. Helpful comments are provided.
## Multilingual
2018-09-03 07:49:47 +00:00
Introduction currently ships with support for [many languages](https://github.com/victoriadrake/hugo-theme-introduction/tree/master/i18n). Contributions for other language translations are welcome.
2018-09-03 07:49:47 +00:00
2018-11-07 14:08:46 +00:00
To create a new language translation, add the `.toml` file to the `i18n/` folder. See the existing files for the necessary fields.
2018-09-03 07:49:47 +00:00
See the [hugo documentation](https://gohugo.io/content-management/multilingual/) for more details.
## Menu
Introduction contains a default menu. If you want to override this, you can do so by defining a `menu.main` in `config.toml`.
## Google Analytics
Set `googleAnalytics` in `config.toml` to activate Hugo's [internal Google Analytics template](https://gohugo.io/templates/internal/#google-analytics).
2018-11-07 14:08:46 +00:00
## Disqus
2018-09-03 07:49:47 +00:00
Set `disqusshortname` in `config.toml` to activate Hugo's [internal Disqus template](https://gohugo.io/templates/internal/#disqus).
2017-11-13 21:01:53 +00:00
## Custom CSS
You can add custom CSS files by placing them under `assets/` and adding the path to the file to `customCSS` in `config.toml`.
2018-09-03 07:49:47 +00:00
## Issues
2018-09-03 07:49:47 +00:00
2019-07-24 23:51:35 +00:00
If you have a question or get stuck, please [open an issue](https://github.com/victoriadrake/hugo-theme-introduction/issues) for help and to help those who come after you. The more information you can provide, the better!
2017-11-13 21:01:53 +00:00
## Contributing
Contributions for new translations, fixes, and features are welcome.
This theme would not be nearly as awesome without its amazing community of open source [contributors](https://github.com/victoriadrake/hugo-theme-introduction/graphs/contributors). Thank you so much! 🖤
2017-11-13 21:01:53 +00:00
## License
2018-06-08 21:31:55 +00:00
2019-12-29 03:27:19 +00:00
Copyright (C) 2017-2020 [Victoria Drake](https://victoria.dev/)
2018-06-08 21:31:55 +00:00
2019-07-24 23:51:35 +00:00
Licensed under [Apache-2.0](https://github.com/victoriadrake/hugo-theme-introduction/blob/master/LICENSE)