gizeku/hugo-theme-stack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: documentation is now in the same repository as the code

Browse Source 
Demo site will be generated in subfolder /demo
This commit is contained in:
Jimmy Cai
2023-09-11 18:16:29 +02:00
parent 9b643df3aa
commit 692804498d
32 changed files with 2005 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guide/configuration.md
+1
View File
@@ -0,0 +1 @@
## Configuration
docs/guide/getting-started.md
+92
View File
@@ -0,0 +1,92 @@
# Getting Started
::: tip
Try this quickstart template to get started with Stack and Hugo in a few minutes:
https://github.com/CaiJimmy/hugo-theme-stack-starter
:::
## Requirements
Before you start, make sure you have installed Hugo **extended version**. For more information, see [Hugo's documentation](https://gohugo.io/getting-started/installing/).
This theme uses SCSS and TypeScript, that's why Hugo extended version is required. If you are using a non-extended Hugo installation, you will get the following error:
```
Error: Error building site: TOCSS: failed to transform "scss/style.scss" (text/x-scss): this feature is not available in your current Hugo version
```
Once you have installed Hugo, you can check the version by running the following command:
```bash
hugo version
```
Which should output something like this (the version number may be different), notice the `extended` keyword:
```
hugo v0.102.3-b76146b129d7caa52417f8e914fc5b9271bf56fc+extended windows/amd64 BuildDate=2022-09-01T10:16:19Z VendorInfo=gohugoio
```
The minimum required Hugo version can be seen in the [theme's `theme.toml` file](https://github.com/CaiJimmy/hugo-theme-stack/blob/master/theme.toml#L23)
## Installation
### Git
On the master branch, you can find the theme's latest source code. To use the latest version, you can clone the repository to `themes/hugo-theme-stack` by running the following command in the root directory of your Hugo site:
```bash
git clone https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack
```
If you are already using Git for your site, you can add the theme as a submodule by running the following command in the root directory of your Hugo site:
```bash
git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack
```
### Hugo module
::: warning
Using this method, there won't be any file under `themes` directory. In order to modify the theme, you will have to copy the file you want to modify to the same directory under `layouts` directory.
For example, in order to modify the `themes/hugo-theme-stack/layouts/partials/header.html` file, you will have to copy it to `layouts/partials/header.html` and modify it there (copy the code from theme's repository). The same applies to `assets` and `static` directories.
:::
This theme is also available as a [Hugo module](https://gohugo.io/hugo-modules/). Run the following command in the root directory of your Hugo site:
First turn your site into a Hugo module (in case you haven't done it yet):
```sh
hugo mod init github.com/me/my-new-blog
```
Then import the theme as a dependency adding the following line to the `module` section of your site's configuration file.
```toml
# config.toml
[[module.imports]]
path = "github.com/CaiJimmy/hugo-theme-stack/v3"
```
```yaml
# config.yaml
module:
imports:
- path: github.com/CaiJimmy/hugo-theme-stack/v3
```
This makes Hugo use the latest stable `v3` version of the theme (available in release page, which probably won't coincide with the latest commit in the `master` branch).
To update the theme to the latest version, run the following command:
```sh
hugo mod get -u github.com/CaiJimmy/hugo-theme-stack/v3
hugo mod tidy
```
::: info
In the future, if a new major version of the theme is released, you will need to manually update the version number in the `path` field.
:::
### Download manually (not recommended)
You can also download the theme from the [release page](https://github.com/CaiJimmy/hugo-theme-stack/releases) and extract it to `themes/hugo-theme-stack` directory.
docs/guide/index.md
+54
View File
@@ -0,0 +1,54 @@
# Welcome
Stack is a simple card-style Hugo theme designed for Bloggers. Here are some of the features:
* Responsive images support
* Lazy load images
* Dark mode
* Local search
* [PhotoSwipe](https://photoswipe.com/) integration
* Archive page template
* Full native JavaScript, no jQuery or any other frameworks are used
* No CSS framework, keep it simple and minimal
* Properly cropped thumbnails
* Subsection support
* Table of contents
## Copyright
**Licensed under the GNU General Public License v3.0**
Please do not remove the "*Theme Stack designed by Jimmy*" text and link.
If you want to port this theme to another blogging platform, please let me know🙏.
## Sponsoring
If you like this theme, give it a star, and consider supporting its development:
<iframe src="https://github.com/sponsors/CaiJimmy/button" title="Sponsor CaiJimmy" height="35" width="116" style="border: 0;"></iframe>
<a href='https://ko-fi.com/C0C530AXX' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi2.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
Your support is greatly appreciated :)
## Thanks to
| Project | Licence |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [PhotoSwipe](https://photoswipe.com/) | [MIT](https://github.com/dimsemenov/PhotoSwipe/blob/master/LICENSE) |
| [Normalize.css](https://github.com/necolas/normalize.css) | [MIT](https://github.com/necolas/normalize.css/blob/master/LICENSE.md) |
| [Node Vibrant](https://github.com/Vibrant-Colors/node-vibrant) | [MIT](https://github.com/Vibrant-Colors/node-vibrant/blob/master/LICENSE.md) |
| [Tabler icons](https://github.com/tabler/tabler-icons) | [MIT](https://github.com/tabler/tabler-icons/blob/master/LICENSE) |
| [jonsuh/hamburgers](https://github.com/jonsuh/hamburgers) | [MIT](https://github.com/jonsuh/hamburgers/blob/master/LICENSE) |
| [lepture/yue.css](https://github.com/lepture/yue.css) | MIT |
| [Typlog](https://typlog.com/) | The author gave me the permission |
| [xieranmaya/blog#6](https://github.com/xieranmaya/blog/issues/6) | - |
### References
Some references that I took while building this theme:
| Project | Licence |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [artchen/hexo-theme-element](https://github.com/artchen/hexo-theme-element) | [MIT](https://github.com/artchen/hexo-theme-element/blob/master/LICENSE) |
| [MunifTanjim/minimo](https://github.com/MunifTanjim/minimo) | [MIT](https://github.com/MunifTanjim/minimo/blob/master/LICENSE) |
docs/guide/modify-theme.md
+22
View File
@@ -0,0 +1,22 @@
# Modify theme
Depending on how you installed the theme, it might be harder or easier to modify it.
## Hugo module
Using this method, there won't be any file under `themes` directory. In order to modify the theme, you will have to copy the file you want to modify to the same directory under `layouts` directory.
For example, in order to modify the `themes/hugo-theme-stack/layouts/partials/head/custom.html` file, you will have to copy it to `layouts/partials/head/custom.html` and modify it there (copy the code from theme's repository).
The same applies to `assets` and `static` directories.
## Git submodule
::: tip
The method described above for Hugo module works here too. In fact it's the recommended way for small changes.
:::
If you installed the theme through Git / Git submodule, you can modify the theme file directly and see the changes in your local site.
However, **you can not commit and push the changes directly** since you don't have the permission to push to the theme repository.
You need to **fork** the theme repository and push your changes to your forked repository (change submodule's repository url). Then, you can commit those changes to your site repository.