Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/CyrusYip/hugo-theme-yue

A minimal, multilingual and customizable Hugo theme, suitable for blogging
https://github.com/CyrusYip/hugo-theme-yue

hugo hugo-theme hugo-theme-yue

Last synced: 2 days ago
JSON representation

A minimal, multilingual and customizable Hugo theme, suitable for blogging

Awesome Lists containing this project

README 

        
# Yue



**[Demo website](https://yue.cyrusyip.org/)** | [Changelog](CHANGELOG.md)



Yue is a minimal, multilingual and customizable Hugo theme, suitable for blogging.



## Screenshots



Screenshots may be outdated, so it's better to visit the [demo website](https://yue.cyrusyip.org/).



  Light mode on desktop

  

  ![light-desktop](https://cdn.jsdelivr.net/gh/CyrusYip/hugo-theme-yue@images/light-desktop.png)



  Dark mode on desktop

  

  ![dark-desktop](https://cdn.jsdelivr.net/gh/CyrusYip/hugo-theme-yue@images/dark-desktop.png)



  Light mode on mobile

  

  ![light-mobile](https://cdn.jsdelivr.net/gh/CyrusYip/hugo-theme-yue@images/light-mobile.png)



  Dark mode on mobile

  

  ![dark-mobile](https://cdn.jsdelivr.net/gh/CyrusYip/hugo-theme-yue@images/dark-mobile.png)



## Features



- Minimal appearance

- Easy to install (with Git and Hugo installed, create a website in a few seconds)

- Detailed documentation

- Automatic dark mode

- Multilingual

    - Translation list in single page

    - Language selector (go to corresponding page or homepage)

- Multiple authors

- Table of Content (foldable, only generated when available)

- Modification date on home page, single page, section page and term page

- Custom date format

- Pagination on home page and section page

- Full-text RSS

- Tags and categories

- Copyright notice (author and year span can be set)

- RSS link

- Heading anchor link

- Mobile-first and responsive

- SCSS

- Search engine optimization

    - [Microdata](https://developer.mozilla.org/en-US/docs/Web/HTML/Microdata)

    - meta description

- [Open Graph](https://ogp.me/)

- Page count to sections (`/posts/`, `/tags/`, etc.)

- Customization

    - Favicon

    - Styles (SCSS)

    - Contents (HTML)



To find out all features, check [hugo.yaml](hugo.yaml) (default configuration) and [exampleSite/hugo.yaml](exampleSite/hugo.yaml) (demo site's configuration).



## Get started



### Install



Install [Git](https://git-scm.com/downloads) and latest [Hugo extended](https://gohugo.io/installation/).



```shell

# Create website

git init my-website

cd my-website

# Install theme

git submodule add --depth=1 https://github.com/CyrusYip/hugo-theme-yue themes/hugo-theme-yue

git commit --message "add theme"

# Create demo content

cp --recursive themes/hugo-theme-yue/exampleSite/* .

# Preview

hugo server

```



Now we have a working demo webiste. The `content` directory contains the content, and `hugo.yaml` is configuration file. Feel free to play around with them.



### Update theme



```shell

cd my-website

git submodule update --remote

```



It's recommended to read [CHANGELOG.md](CHANGELOG.md) before updating the theme.



You can subscribe updates and the changelog in a feed aggregator (e.g. Inoreader).



- Updates: 

- Changelog: 



### Clone website



You need to use additional options when you clone your website project.



```shell

git clone --recurse-submodules --shallow-submodules [email protected]:your-user-name/my-website.git

```



### Deploy



After setting up the website, you probably want to host it on Internet. There are many methods for doing it, see [Hosting and deployment | Hugo](https://gohugo.io/hosting-and-deployment/). If you don't know what to choose, you can start from Netlify, see [Host on Netlify | Hugo](https://gohugo.io/hosting-and-deployment/hosting-on-netlify/).



Make sure you change baseURL to your domain name (e.g. `https://my-cool-domain.org/`) in `hugo.yaml`.



```diff

-baseURL: https://yue.cyrusyip.org/

+baseURL: https://my-cool-domain.org/

```



Recommended build command:



```shell

hugo --gc --minify

```



`--gc` remove unused cache files

, and `--minify` reduce the size of the website (mainly HTML).



## Usage



Create a new post.



```

hugo new content content/en/posts/my-first-post.md

```



To learn more about usage, see:



- [Basic usage | Hugo](https://gohugo.io/getting-started/usage/)

- [Directory structure | Hugo](https://gohugo.io/getting-started/directory-structure/)



## Config



Settings are listed in [exampleSite/hugo.yaml](exampleSite/hugo.yaml) (demo site's config) and [hugo.yaml](hugo.yaml) (default config, imported by the former).



In the root of your website project, `hugo.yaml` is the config file, which is a copy of [exampleSite/hugo.yaml](exampleSite/hugo.yaml).



To learn configuration, see [Configure Hugo | Hugo](https://gohugo.io/getting-started/configuration/).



### Multilingual mode



Supported languages:



- `en`: English

- `fr`: French

- `zh-CN`: Simplified Chinese



To create a multilingual website, see [Multilingual mode | Hugo](https://gohugo.io/content-management/multilingual/) and [exampleSite/hugo.yaml](exampleSite/hugo.yaml).



Translation files are located in the [i18n](i18n) directory and [data/i18n.yaml](data/i18n.yaml). Contributions for additional languages are welcome.



To contribute a new language:



1. Create a language file (e.g., `fr.yaml` for French) in the [i18n](i18n) directory.

1. Copy the content of [i18n/en.yaml](i18n/en.yaml) into the new file.

1. Remove all comments (`# ...`) and translate the content.

1. Translate the content in [data/i18n.yaml](data/i18n.yaml) as well.



If you want to keep contributing to translation, you can get latest changes by subscribing the feed of [i18n/en.yaml](i18n/en.yaml) () using an RSS reader.



#### Title of tags and categories



If your website is not in English, you probably want to customize title of `/tags` and `/categories`.



For example, to customize `/tags` title of `zh-CN` website, create `content/zh-CN/tags/_index.md` and add the following content into the file.



```

---

title: Chinese Tags

---

```



## Customize



Yue allows you to customize favicon, styles (SCSS), and contents (HTML).



### Favicon



Favicon is the icon next to title in a browser tab. To use your favicon, put `favicon.ico` under `static` directory. You can create `favicon.ico` on online favicon.ico generators.



### Styles (SCSS)



Yue uses SCSS (libsass) to add styles. All files are in [assets/scss](assets/scss).To customize styles, create `assets/scss/_style-start.scss` and `assets/scss/_style-end.scss`.



`_style-start.scss` is applied first, and you can override variables in this file.



```scss

$base-font-size: 15px;

```



`_style-end.scss` is applied last, and you can add styles in this file.



Vanilla CSS is also valid in SCSS.



References:



- [CSS: Cascading Style Sheets | MDN](https://developer.mozilla.org/en-US/docs/Web/CSS)

- [Sass: Sass Basics](https://sass-lang.com/guide/)

- [Directory structure | Hugo](https://gohugo.io/getting-started/directory-structure/)



### Contents (HTML)



You can create these files to insert HTML code.



- `layouts/partials/head/head-start.html`

- `layouts/partials/head/head-end.html`

- `layouts/partials/single/single-end.html`

- `layouts/partials/body/body-end.html`



#### head-start.html



`head-start.html` is added near the start of the `` element.



Use cases:



- Preload scripts

- Load scripts

- Load styles



Here is an example of preloading scripts:



```html



```



#### head-end.html



`head-end.html` is added to the end of the `` element.



Use cases:



- Load scripts

- Load styles



Here is an example of adding Google Analytics and a local script:



```html



  window.dataLayer = window.dataLayer || [];

  function gtag(){dataLayer.push(arguments);}

  gtag('js', new Date());



  gtag('config', 'G-F46B15BRUF');



{{ with resources.Get "js/my-script.js" | js.Build }}

  

{{ end }}

```



#### single-end.html



`single-end.html` is added to the end of the `` element in a post.



Use cases:



- comment services, e.g., Disqus and giscus



Here is an example of adding [Giscus](https://giscus.app/):



```html

{{ $language := "" }}

{{- /*

Workaround for lowercase LanguagePrefix,

see https://github.com/gohugoio/hugo/issues/9404

*/ -}}

{{ if eq site.LanguagePrefix "/zh-cn" }}

  {{ $language = "zh-CN" }}

{{ else }}

  {{ $language = "en" }}

{{ end }}



```



List of comment services: [Comments | Hugo](https://gohugo.io/content-management/comments/).



#### body-end.html



`body-end.html` is added to the end of the `` element.



Use cases:



- Dynamically load scripts



## Support



To report bugs, submit an [issue](https://github.com/CyrusYip/hugo-theme-yue/issues). To ask questions, start a [discussion](https://github.com/CyrusYip/hugo-theme-yue/discussions).



## Further reading



Hugo has many features, read [Hugo Documentation](https://gohugo.io/documentation/) to learn.



## Changelog



See [CHANGELOG.md](CHANGELOG.md).



## Development



This project uses [hugo-bin - npm](https://www.npmjs.com/package/hugo-bin) to manage Hugo version. Prerequisite: [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).



Clone this repository.



```shell

npm install

npm run clean:server:shared

```



There are other useful commands listed in [package.json](package.json). To use recommended Hugo version, run `npx hugo`.



---



If you don't have Node.js and npm installed, just install the version listed in [package.json](package.json).



```json

"hugo-bin": {

  "buildTags": "extended",

  "version": "x.yyy.z"

},

```



CHANGELOG.md should be updated in each commit.



## Websites built with Yue



If you are using Yue and source code of your website is hosted on GitHub, you can add `hugo-theme-yue` topic to your repository.



[Link to `hugo-theme-yue` topic](https://github.com/topics/hugo-theme-yue).



## Acknowledgement



I have learned a lot from many projects. Thank you, developers.



- [hugo-xmin](https://github.com/yihui/hugo-xmin/) (minimal templates)

- [hugo-theme-jane](https://github.com/xianmin/hugo-theme-jane/) ([RSS template](https://github.com/xianmin/hugo-theme-jane/blob/6bef93b29e96bcf8b5b9a86b94cdd0dce99002bc/layouts/rss.xml#L30))

- [hugo-theme-zen](https://github.com/frjo/hugo-theme-zen) ([language selector](https://github.com/frjo/hugo-theme-zen/blob/d3b2b6e1eea2bc67b3409238b9c347ab628876da/layouts/partials/language-selector.html))

- [hugo-theme-gruvbox](https://github.com/schnerring/hugo-theme-gruvbox) (color)

- [gruvbox](https://github.com/morhetz/gruvbox) (color)

- [hugo-theme-stack](https://github.com/CaiJimmy/hugo-theme-stack) (source code, documentation and config)

- [hugo-PaperMod](https://github.com/adityatelange/hugo-PaperMod) (source code, documentation and config)



## License



This project is licensed under [MIT](LICENSE).