hugo-theme-hyde-hyde/README.md

203 lines
10 KiB
Markdown
Raw Normal View History

[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](https://github.com/htr3n/hyde-hyde/blob/master/LICENSE.md) ![GitHub release](https://img.shields.io/github/release/htr3n/hyde-hyde.svg) ![GitHub stars](https://img.shields.io/github/stars/htr3n/hyde-hyde.svg) ![GitHub forks](https://img.shields.io/github/forks/htr3n/hyde-hyde.svg) ![GitHub issues](https://img.shields.io/github/issues/htr3n/hyde-hyde.svg) ![GitHub issues closed](https://img.shields.io/github/issues-closed/htr3n/hyde-hyde.svg)
2018-10-17 05:39:56 +00:00
# Hyde-hyde
2014-04-26 22:25:13 +00:00
__`Hyde-hyde`__ is a [Hugo](https://gohugo.io)'s theme inspired and derived from @spf13's [Hyde](https://github.com/spf13/hyde.git) and [Nate Finch's blog](https://npf.io).
2018-01-21 14:17:19 +00:00
> NOTICE: Maintainers / collaborators seeking: As I'm underwater with my full time job at the moment, I'm actively looking for and welcome any new maintainers or collaborators. If you are interested, comment on [#130](https://github.com/htr3n/hyde-hyde/issues/130) and I can add you to the project. TIA.
2018-07-21 23:33:29 +00:00
## Breaking Changes
2018-04-09 03:02:19 +00:00
2018-07-21 23:33:29 +00:00
Since version 2.0, __`hyde-hyde`__ has been overhauled and, therefore, might cause some disruptions.
2019-02-17 19:37:55 +00:00
* The main styles are refactored and redeveloped using SCSS (see [_assets/scss_](https://github.com/htr3n/hyde-hyde/blob/master/assets/scss)), `poole.css` and `hyde.css` are no longer needed because `hyde-hyde.scss` already incorporates relevant elements (I still keep them there for reference purpose)
* Per PR [#45 by [@jd4no](https://github.com/jd4no), `hyde-hyde` can use SCSSs directly in the templates instead of the generated CSSs. The generated CSSs and the generated resources are still kept in `hyde-hyde` in order to ensure the demo on [Hugo theme site](https://themes.gohugo.io) working.
2018-07-28 00:44:26 +00:00
* The layouts have been heavily restructured and modularised further (see [_layouts_](https://github.com/htr3n/hyde-hyde/blob/master/layouts))
* Adding '[_Portfolio_](https://github.com/htr3n/hyde-hyde/blob/master/layouts/portfolio)' page inspired by Xiaoying Riley (@3rdwave_themes) [Developer-Theme](https://github.com/xriley/developer-theme)
2018-07-21 23:33:29 +00:00
* Switching to use system fonts instead of Web fonts (e.g. privacy issues)
2018-09-20 07:12:59 +00:00
* Experimenting a collapsible menu in mobile mode
2018-09-29 23:32:57 +00:00
* Adding _Table of Contents_
* Configure using `.Site.Params.toc` with two possible value: "hugo" (using Hugo `{{ .TableOfContents }}`, and "tocbot" (using [Tocbot](https://tscanlin.github.io/tocbot/)), remove `.Site.Params.toc` to disable TOC
2019-12-21 00:38:57 +00:00
* Tocbot can be configured in [layouts/partials/page-single/footer.html](layouts/partials/page-single/footer.html) with options as described in [its documentation](https://tscanlin.github.io/tocbot/#api)
2018-07-21 23:33:29 +00:00
For more details, please refer to [CHANGELOG](https://github.com/htr3n/hyde-hyde/blob/master/CHANGELOG.md). A real site in action can be found [here](https://htr3n.github.io) and its [WIP source](https://github.com/htr3n/htr3n-blog) for reference.
2018-07-21 23:33:29 +00:00
## Usage
2014-04-26 22:25:13 +00:00
2018-07-29 11:43:15 +00:00
### Installation
2016-07-26 12:27:07 +00:00
2018-07-21 23:33:29 +00:00
__`Hyde-hyde`__ can be easily installed as many other Hugo themes:
2016-07-26 12:27:07 +00:00
```sh
2018-07-21 23:33:29 +00:00
$ cd HUGO_PROJECT
# then either clone hyde-hyde
$ git clone https://github.com/htr3n/hyde-hyde.git themes/hyde-hyde
2018-07-21 23:33:29 +00:00
# or just add hyde-hyde as a submodule
$ git submodule add https://github.com/htr3n/hyde-hyde.git themes/hyde-hyde
2014-04-26 22:25:13 +00:00
```
2018-07-21 23:33:29 +00:00
After that, choose `hyde-hyde` as the main theme.
2014-04-26 22:25:13 +00:00
* `config.toml`
2014-04-26 22:25:13 +00:00
2018-07-21 23:33:29 +00:00
```toml
2018-01-21 11:50:25 +00:00
theme = "hyde-hyde"
```
2018-01-21 14:17:19 +00:00
* `config.yaml`
2014-04-26 22:25:13 +00:00
2018-01-21 11:50:25 +00:00
```yaml
theme : "hyde-hyde"
2014-04-26 22:25:13 +00:00
```
That's all. You can render your site using `hugo` and see `hyde-hyde` in action.
2018-07-29 11:43:15 +00:00
### Options
2018-07-29 21:42:24 +00:00
__`Hyde-hyde`__ essentially inherits most of Hyde's [options](https://github.com/spf13/hyde#options). There are some extra options though
* `highlightjs = true`: use [highlight.js](https://highlightjs.org) instead of Hugo built-in support for code highlighting
2018-08-15 00:28:59 +00:00
* `highlightjsstyle="highlight-style"`: only when `highlightjs = true`, please choose one of many _highlight.js_'s [styles](https://highlightjs.org/static/demo).
* Since [v2.0.1](https://github.com/htr3n/hyde-hyde/tree/v2.0.1), highlighting for each page can be fine-tuned in the front matter, for example
* `highlight = false` (default `true`)
* `highlightjslanguages = ["swift", "objectivec"]`
2018-07-29 21:42:24 +00:00
* `postNavigation = true|false` (default `true`): Setting to `false` will disable the navigation _Previous Post_/ _Next Post_
* `relatedPosts = false|true` (default `false`): Setting to `true` allows related posts. Please refer [here](https://gohugo.io/content-management/related) for more details on related contents with Hugo.
* `GraphCommentId = "your-graphcomment-id"`: to use [GraphComment](https://graphcomment.com) instead of the built-in [Disqus](https://disqus.com). This option should be used exclusively with `disqusShortname = "disqus-shortname"`.
2019-11-06 23:12:21 +00:00
* `UtterancesRepo = "owner/repo-name"`: to use [Utterances](https://utteranc.es/) instead of the built-in [Disqus](https://disqus.com). This option should be used exclusively with `disqusShortname = "disqus-shortname"`.
2018-11-02 03:17:45 +00:00
* `UtterancesIssueTerm = "pathname"` Method for Utterances to match issue's to posts (pathname, url, title, og:title)
* `UtterancesTheme = "github-light"` Theme for Utterances (github-light, github-dark)
2018-11-02 03:17:45 +00:00
* `Commento = true`: to use [Commento](https://commento.io/) instead of the built-in [Disqus](https://disqus.com). This option should be used exclusively with `disqusShortname = "disqus-shortname"`.
* `CommentoHost = "your-commento-instance"` [Self-hosted Commento](https://docs.commento.io/installation/self-hosting/) instance. This is not required if you're a [Commento.io](https://commento.io) user.
2018-07-29 21:42:24 +00:00
* `[params.social]`: in this section, you can set many social identities such as Twitter, Facebook, Github, Bitbucket, Gitlab, Instagram, LinkedIn, StackOverflow, Medium, Xing, Keybase.
2018-08-15 00:28:59 +00:00
```toml
[params.social]
twitter = "htr3n"
keybase = "htr3n"
github = "htr3n"
...
```
* `include_toc = false`: Setting to `false` in FrontMatter will disable too short TOC data as your want.
2018-07-29 21:42:24 +00:00
* Per PR [#56](https://github.com/htr3n/hyde-hyde/commit/5ed13e17400bbc09a342b60fd50cd9fe3e6f1525), Gravatar pics can be used exclusively to `.Site.Params.authorimage` via the parameter `.Site.Params.social.gravatar`
* ```toml
[params.social]
gravatar = "your.email@domain.com"
```
2018-07-29 11:43:15 +00:00
### Customisations
2019-02-17 19:37:55 +00:00
* Most of the customisable SCSS styles in [_assets/scss/hyde-hyde_](https://github.com/htr3n/hyde-hyde/blob/master/assets/scss/hyde-hyde) and Hugo templates in [_hyde-hyde/layouts_](https://github.com/htr3n/hyde-hyde/blob/master/layouts) are modularised and can be altered/adapted easily.
## Portfolio
Since version 2.0+, I added a portfolio page just in case. If you need it, simply add a menu section '_Portfolio_' in `config.toml` as following.
```toml
[[menu.main]]
name = "Portfolio"
identifier = "portfolio"
2018-09-29 23:32:57 +00:00
weight = xyz
url = "/portfolio/"
```
In the folder `content` , create a subfolder `portfolio` and use the following folder/content structure as reference.
```
$ tree portfolio
portfolio
├── _index.md
├── p1.md
├── p1.png
├── p2.md
├── p2.png
...
├── pn.md
└── pn.png
```
As I design the section _portfolio_ to be rendered as _list_, `_index.md` can be used to set the title for your portfolio (you can read more about `_index.md` [here](https://gohugo.io/content-management/organization/#index-pages-index-md)). For instance, when I want to set the title of my portfolio "_Projects_", the front matter of `_index.md` will be:
```markdown
---
title: 'Projects'
---
```
The remaining of `_index.md` will be ignored.
For each project, just create a Markdown file with the following parameters in the front matter:
```markdown
---
title: "Project P1's Title"
description: "A short description"
date: '2018-01-02'
link: 'https://project-p1.com'
screenshot: 'p1.png'
layout: 'portfolio'
featured: true
---
Here is a longer summary of the project. You can write as long as you wish.
```
> __Note__:
>
> * `date` is important to sort the project chronologically
> * `layout 'portfolio'` is important as you don't want your project's page appear in the list of posts in the main page of your Web site but only in the _Portfolio_ ;)
> * `featured: true` : when you want to show a project as featured project. It is default to `false`. Note that only one project should be marked `featured: true` , otherwise, the result could be random as [the Hugo template](https://github.com/htr3n/hyde-hyde/blob/master/layouts/partials/portfolio/content.html) will take the first one.
> * The body of the Markdown file will be the summary of the project.
2019-02-17 19:37:55 +00:00
If you want to adjust the portfolio page to your needs, please have a look at the [main template](https://github.com/htr3n/hyde-hyde/blob/master/layouts/portfolio/list.html), that uses this [partial template](https://github.com/htr3n/hyde-hyde/blob/master/layouts/partials/portfolio/content.html) and [this SCSS style](https://github.com/htr3n/hyde-hyde/blob/master/assets/scss/hyde-hyde/_project.scss).
### Posts in home page
By default hugo will show in your home page the most populated section.
This means that if you have more projects than posts, by default your home page will list your projects instead of your posts.
If you want to change this behaviour you can change the [mainsections](https://gohugo.io/functions/where/#mainsections).
For example, for the [exampleSite](https://github.com/htr3n/hyde-hyde/tree/master/exampleSite) this is how you should change the `config.toml` file:
```
[params]
mainSections = ["posts"]
```
## Some Screenshots
2018-07-29 11:43:15 +00:00
### Main page
![hyde-hyde main screen](https://github.com/htr3n/hyde-hyde/raw/master/images/main.png)
2018-07-29 11:43:15 +00:00
### A post
![A post in hyde-hyde](https://github.com/htr3n/hyde-hyde/raw/master/images/post.png)
2018-07-29 11:43:15 +00:00
### Portfolio
![Portfolio hyde-hyde](https://github.com/htr3n/hyde-hyde/raw/master/images/portfolio.png)
2018-04-09 03:02:19 +00:00
2018-09-20 07:12:59 +00:00
### Mobile Mode with Collapsible Menu
2018-09-20 07:17:41 +00:00
<img src='https://github.com/htr3n/hyde-hyde/raw/master/images/mobile.png' alt='hyde-hyde in mobile mode' width='60%'>
2018-07-07 00:14:01 +00:00
2018-09-20 07:12:59 +00:00
## Author(s)
2018-09-20 07:12:59 +00:00
* Original developed by [Mark Otto](https://github.com/mdo)
2014-04-26 22:25:13 +00:00
2018-09-20 07:12:59 +00:00
* Hugo's `hyde` ported by [Steve Francia](https://github.com/spf13)
2014-04-26 22:25:13 +00:00
## License
2018-09-20 07:12:59 +00:00
Open sourced under the [MIT license](LICENSE.md)