From 67451fc5d7ef348df0adbd76b1fa77ce92f1111d Mon Sep 17 00:00:00 2001 From: Victoria Drake Date: Mon, 20 Jan 2020 10:10:22 -0500 Subject: [PATCH] Update README - Linting - Update quick start instruction - Update links --- README.md | 86 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 47 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index ab5d94c..649ddfb 100644 --- a/README.md +++ b/README.md @@ -10,58 +10,63 @@ Introduction is a minimalist, highly-versatile theme for Hugo. It can be configu Features: -* 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` -* Styled Markdown throughout with syntax highlighting +- 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` +- Styled Markdown throughout with syntax highlighting 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 +- 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 -# Getting started -## Requirements -- Extended version of [Hugo](https://gohugo.io/getting-started/installing/) (latest version recommended) -- To make changes to the theme CSS: - - [autoprefixer](https://github.com/postcss/autoprefixer): `npm install -g autoprefixer` - - [postcss-cli](https://github.com/postcss/postcss-cli):`npm install -g postcss-cli` +## Getting started + +- Requres 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`: + +- [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). 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 cd exampleSite/ -npm install autoprefixer npm install postcss-cli +npm install autoprefixer ``` ## Get the theme + Run from the root of your Hugo site: + ```sh -$ git clone https://github.com/victoriadrake/hugo-theme-introduction.git themes/introduction +git clone https://github.com/victoriadrake/hugo-theme-introduction.git themes/introduction ``` 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: ```sh -$ git submodule add https://github.com/victoriadrake/hugo-theme-introduction.git themes/introduction +git submodule add https://github.com/victoriadrake/hugo-theme-introduction.git themes/introduction ``` ## Preview the theme Introduction ships with an fully configured example site. For a quick preview: -``` +```sh cd exampleSite/ hugo serve --themesDir ../.. ``` Then visit `http://localhost:1313/` in your browser to view the example site. - -# Add content +## Add content The following explains how to add content to your Hugo site. You can find sample content in the `exampleSite/` folder. @@ -69,7 +74,7 @@ The following explains how to add content to your Hugo site. You can find sample Create `index.md`: -``` +```sh hugo new home/index.md ``` @@ -88,7 +93,7 @@ Each markdown file will show as a section on the home page and can be ordered by You may add a contact section by creating `contact.md`: -``` +```sh hugo new home/contact.md ``` @@ -100,7 +105,7 @@ Introduction provides an easy way to showcase your projects. Each project can ev Start by creating an index file for the projects section: -``` +```sh hugo new projects/_index.md ``` @@ -109,7 +114,7 @@ Add an optional `weight` for ordering projects section. To create a project, run: -``` +```sh hugo new projects/YourProjectName/index.md ``` @@ -119,7 +124,7 @@ 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: -``` +```sh resources: - src: NameOfYourImage.jpg params: @@ -130,27 +135,27 @@ resources: Create an index file for the blog: -``` +```sh hugo new blog/_index.md ``` + Add an optional `weight` for ordering blog section on your homepage Create a new blog post with: -``` +```sh hugo new blog/YourEntryTitle.md ``` Posts will also display in the Blog section of the home page. - -# Configure your site +## Configure your site 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 Mode +## Multilingual -Introduction currently ships with support for English, German, Spanish and French. Contributions for other language translations are welcome. +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. To create a new language translation, add the `.toml` file to the `i18n/` folder. See the existing files for the necessary fields. @@ -168,19 +173,22 @@ Set `googleAnalytics` in `config.toml` to activate Hugo's [internal Google Analy Set `disqusshortname` in `config.toml` to activate Hugo's [internal Disqus template](https://gohugo.io/templates/internal/#disqus). -## 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`. +## Custom CSS -# Issues +You can add custom CSS files by placing them under `assets/` and adding the path to the file to `customCSS` in `config.toml`. + +## Issues 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! -# Contributing -This theme would not be nearly as awesome without its amazing community of open source contributors, who are [listed here.](https://github.com/victoriadrake/hugo-theme-introduction/releases) Thank you so much! 🖤 +## Contributing -Pull requests for bug fixes and improvements are welcome. +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! 🖤 + +## License -# License Copyright (C) 2017-2020 [Victoria Drake](https://victoria.dev/) Licensed under [Apache-2.0](https://github.com/victoriadrake/hugo-theme-introduction/blob/master/LICENSE)