hyzen/hyzendust.github.io
1
0
Fork 0
mirror of https://github.com/hyzendust/hyzendust.github.io.git synced 2026-02-15 08:01:12 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
abcd234f49e6ee97f90fd224123357a1cb2cea47
hyzendust.github.io/themes/hugo-theme-yue/README.md
psychhim 27a08b46f6 Fix: remove submodule
2025-11-11 18:07:05 +05:30

377 lines
11 KiB
Markdown
Raw Blame History

# 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/).
<details open>
<summary>Light mode on desktop</summary>
![light-desktop](https://cdn.jsdelivr.net/gh/CyrusYip/hugo-theme-yue@images/light-desktop.png)
</details>
<details>
<summary>Dark mode on desktop</summary>
![dark-desktop](https://cdn.jsdelivr.net/gh/CyrusYip/hugo-theme-yue@images/dark-desktop.png)
</details>
<details>
<summary>Light mode on mobile</summary>
![light-mobile](https://cdn.jsdelivr.net/gh/CyrusYip/hugo-theme-yue@images/light-mobile.png)
</details>
<details>
<summary>Dark mode on mobile</summary>
![dark-mobile](https://cdn.jsdelivr.net/gh/CyrusYip/hugo-theme-yue@images/dark-mobile.png)
</details>
## 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: <https://github.com/CyrusYip/hugo-theme-yue/commits/main.atom>
- Changelog: <https://github.com/CyrusYip/hugo-theme-yue/commits/main/CHANGELOG.md.atom>
### Clone website
You need to use additional options when you clone your website project.
```shell
git clone --recurse-submodules --shallow-submodules git@github.com: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:
- `ar`: Arabic
- `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) (<https://github.com/CyrusYip/hugo-theme-yue/commits/main/i18n/en.yaml.atom>) 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/page/page-end.html`
- `layouts/_partials/body/body-end.html`
#### head-start.html
`head-start.html` is added near the start of the `<head>` element.
Use cases:
- Preload scripts
- Load scripts
- Load styles
Here is an example of preloading scripts:
```html
<link rel="preload" as="script" href="https://unpkg.com/@swup/head-plugin@2">
<link rel="preload" as="script" href="https://unpkg.com/@swup/preload-plugin@3">
<link rel="preload" as="script" href="https://unpkg.com/swup@4">
```
#### head-end.html
`head-end.html` is added to the end of the `<head>` element.
Use cases:
- Load scripts
- Load styles
Here is an example of adding Google Analytics and a local script:
```html
<!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-F46B15BRUF"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-F46B15BRUF');
</script>
<!-- Local script, path: assets/js/my-script.js -->
{{ with resources.Get "js/my-script.js" | js.Build }}
<script defer src="{{ .RelPermalink }}"></script>
{{ end }}
```
#### page-end.html
`page-end.html` is added to the end of the `<main>` 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 }}
<script src="https://giscus.app/client.js"
data-repo="CyrusYip/yue-test"
data-repo-id="P_9hJMbXtqr"
data-category="General"
data-category-id="SIB_ldsflk712ldRsjf7"
data-mapping="pathname"
data-strict="0"
data-reactions-enabled="1"
data-emit-metadata="0"
data-input-position="bottom"
data-theme="preferred_color_scheme"
data-lang="{{ $language }}"
crossorigin="anonymous"
async>
</script>
```
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 `<body>` 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).
Reference in New Issue View Git Blame Copy Permalink