|
| 1 | +[](https://github.com/htr3n/hyde-hyde/blob/master/LICENSE.md)      |
| 2 | + |
| 3 | +# Hyde-hyde |
| 4 | + |
| 5 | +__`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). |
| 6 | + |
| 7 | +## Breaking Changes |
| 8 | + |
| 9 | +Since version 2.0, __`hyde-hyde`__ has been overhauled and, therefore, might cause some disruptions. |
| 10 | + |
| 11 | +* 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) |
| 12 | + * 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. |
| 13 | +* The layouts have been heavily restructured and modularised further (see [_layouts_](https://github.com/htr3n/hyde-hyde/blob/master/layouts)) |
| 14 | +* 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) |
| 15 | +* Switching to use system fonts instead of Web fonts (e.g. privacy issues) |
| 16 | +* Experimenting a collapsible menu in mobile mode |
| 17 | +* Adding _Table of Contents_ |
| 18 | + * 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 |
| 19 | + * 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) |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +## Usage |
| 24 | + |
| 25 | +### Installation |
| 26 | + |
| 27 | +__`Hyde-hyde`__ can be easily installed as many other Hugo themes: |
| 28 | + |
| 29 | +```sh |
| 30 | +$ cd HUGO_PROJECT |
| 31 | + |
| 32 | +# then either clone hyde-hyde |
| 33 | +$ git clone https://github.com/htr3n/hyde-hyde.git themes/hyde-hyde |
| 34 | + |
| 35 | +# or just add hyde-hyde as a submodule |
| 36 | +$ git submodule add https://github.com/htr3n/hyde-hyde.git themes/hyde-hyde |
| 37 | +``` |
| 38 | + |
| 39 | +After that, choose `hyde-hyde` as the main theme. |
| 40 | + |
| 41 | +* `config.toml` |
| 42 | + |
| 43 | +```toml |
| 44 | +theme = "hyde-hyde" |
| 45 | +``` |
| 46 | + |
| 47 | +* `config.yaml` |
| 48 | + |
| 49 | +```yaml |
| 50 | +theme : "hyde-hyde" |
| 51 | +``` |
| 52 | +
|
| 53 | +That's all. You can render your site using `hugo` and see `hyde-hyde` in action. |
| 54 | + |
| 55 | +### Options |
| 56 | + |
| 57 | +__`Hyde-hyde`__ essentially inherits most of Hyde's [options](https://github.com/spf13/hyde#options). There are some extra options though |
| 58 | + |
| 59 | +* `highlightjs = true`: use [highlight.js](https://highlightjs.org) instead of Hugo built-in support for code highlighting |
| 60 | + |
| 61 | + * `highlightjsstyle="highlight-style"`: only when `highlightjs = true`, please choose one of many _highlight.js_'s [styles](https://highlightjs.org/static/demo). |
| 62 | + * 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 |
| 63 | + * `highlight = false` (default `true`) |
| 64 | + * `highlightjslanguages = ["swift", "objectivec"]` |
| 65 | + |
| 66 | +* `postNavigation = true|false` (default `true`): Setting to `false` will disable the navigation _Previous Post_/ _Next Post_ |
| 67 | + |
| 68 | +* `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. |
| 69 | + |
| 70 | +* `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"`. |
| 71 | + |
| 72 | +* `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"`. |
| 73 | + * `UtterancesIssueTerm = "pathname"` Method for Utterances to match issue's to posts (pathname, url, title, og:title) |
| 74 | + * `UtterancesTheme = "github-light"` Theme for Utterances (github-light, github-dark) |
| 75 | + |
| 76 | +* `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"`. |
| 77 | + * `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. |
| 78 | + |
| 79 | +* `[params.social]`: in this section, you can set many social identities such as Twitter, Facebook, Github, Bitbucket, Gitlab, Instagram, LinkedIn, StackOverflow, Medium, Xing, Keybase. |
| 80 | + |
| 81 | + ```toml |
| 82 | + [params.social] |
| 83 | + twitter = "htr3n" |
| 84 | + keybase = "htr3n" |
| 85 | + github = "htr3n" |
| 86 | + ... |
| 87 | + ``` |
| 88 | + |
| 89 | +* `include_toc = false`: Setting to `false` in FrontMatter will disable too short TOC data as your want. |
| 90 | + |
| 91 | + * 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` |
| 92 | + |
| 93 | + * ```toml |
| 94 | + [params.social] |
| 95 | + gravatar = "your.email@domain.com" |
| 96 | + ``` |
| 97 | + |
| 98 | +### Customisations |
| 99 | + |
| 100 | +* 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. |
| 101 | + |
| 102 | +## Portfolio |
| 103 | + |
| 104 | +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. |
| 105 | + |
| 106 | +```toml |
| 107 | +[[menu.main]] |
| 108 | + name = "Portfolio" |
| 109 | + identifier = "portfolio" |
| 110 | + weight = xyz |
| 111 | + url = "/portfolio/" |
| 112 | +``` |
| 113 | + |
| 114 | +In the folder `content` , create a subfolder `portfolio` and use the following folder/content structure as reference. |
| 115 | + |
| 116 | +``` |
| 117 | +$ tree portfolio |
| 118 | +portfolio |
| 119 | +├── _index.md |
| 120 | +├── p1.md |
| 121 | +├── p1.png |
| 122 | +├── p2.md |
| 123 | +├── p2.png |
| 124 | + ... |
| 125 | +├── pn.md |
| 126 | +└── pn.png |
| 127 | +``` |
| 128 | +
|
| 129 | +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: |
| 130 | +
|
| 131 | +```markdown |
| 132 | +--- |
| 133 | +title: 'Projects' |
| 134 | +--- |
| 135 | +``` |
| 136 | +The remaining of `_index.md` will be ignored. |
| 137 | + |
| 138 | +For each project, just create a Markdown file with the following parameters in the front matter: |
| 139 | + |
| 140 | +```markdown |
| 141 | +--- |
| 142 | +title: "Project P1's Title" |
| 143 | +description: "A short description" |
| 144 | +date: '2018-01-02' |
| 145 | +link: 'https://project-p1.com' |
| 146 | +screenshot: 'p1.png' |
| 147 | +layout: 'portfolio' |
| 148 | +featured: true |
| 149 | +--- |
| 150 | +Here is a longer summary of the project. You can write as long as you wish. |
| 151 | +``` |
| 152 | + |
| 153 | +> __Note__: |
| 154 | +> |
| 155 | +> * `date` is important to sort the project chronologically |
| 156 | +> * `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_ ;) |
| 157 | +> * `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. |
| 158 | +> * The body of the Markdown file will be the summary of the project. |
| 159 | +
|
| 160 | +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). |
| 161 | + |
| 162 | +## Some Screenshots |
| 163 | + |
| 164 | +### Main page |
| 165 | + |
| 166 | + |
| 167 | + |
| 168 | +### A post |
| 169 | + |
| 170 | + |
| 171 | + |
| 172 | +### Portfolio |
| 173 | + |
| 174 | + |
| 175 | + |
| 176 | + |
| 177 | + |
| 178 | +### Mobile Mode with Collapsible Menu |
| 179 | + |
| 180 | +<img src='https://github.com/htr3n/hyde-hyde/raw/master/images/mobile.png' alt='hyde-hyde in mobile mode' width='60%'> |
| 181 | + |
| 182 | +## Author(s) |
| 183 | + |
| 184 | +* Original developed by [Mark Otto](https://github.com/mdo) |
| 185 | + |
| 186 | +* Hugo's `hyde` ported by [Steve Francia](https://github.com/spf13) |
| 187 | + |
| 188 | +## License |
| 189 | + |
| 190 | +Open sourced under the [MIT license](LICENSE.md) |
0 commit comments