1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
|
# Argo
## A Hugo Theme
Argo is a clean, minimalist Hugo theme with multilingual support.
The theme follows the principles of meaningful semantic HTML with it's benefits of strong accessibility and SEO, as well as markup readability and beauty.
Argo also strives to be easy to modify, with clearly structured, readable and simple code that is easy to understand.
The theme uses no external dependencies, no frameworks, libraries or language supersets. Only plain HTML, CSS, a bit of JavaScript and of course Go templates.
The usage of JavaScript is limited to the absolute minimum necessary, for the site-wide search and for toggling light/dark mode.
You can see Argo in use on my personal website [arnerief.net](https://arnerief.net).
## Features
- Multilingual support
- Semantic HTML for accessibility and SEO
- Toggle light/dark mode
- Site-wide search
- Fully responsive
## Installation
Once you have [installed Hugo](https://gohugo.io/getting-started/quick-start/) with all it's prerequisites, you need to create a project, change into it's home directory and initialize a git repository.
If you have not done that already, open your terminal and enter the following commands:
```sh
hugo new site your-site-name
cd your-site-name
git init
```
Now you can add Argo as a git submodule to your project, set it as your project's theme and start Hugo's embedded web server with the following commands:
```sh
git submodule add https://codeberg.org/arrief/hugo-Argo.git themes/Argo
echo "theme = 'Argo'" >> hugo.toml
hugo server
```
To update the theme, run the following command inside your project's home directory:
```sh
git submodule update --remote --merge
```
## How to use
Check the `hugo.toml` settings and the examples in the `i18n` directory for reference on how to set up your own project's `hugo.toml` for a multilingual website.
Be sure to copy the lines marked in the theme's `hugo.toml` into that of your own project. Otherwise central features of the theme will not work.
Also note that the theme expects `params.author.name` to be defined, as can be seen in `hugo.toml`.
You will need to create markdown files for the pages **"Search"** and **"All posts"** in your project's content directory.
If you want to go with the default text for both pages, these files can be empty except for title and `layout = all-posts` in the frontmatter. You can simply copy the example md files from the theme's `/content` directory.
In case you have a multilingual setup, you will need to create both pages in each language subdirectory, e.g. `content/de/search.md`, `content/en/all-posts.md` etc.
The theme supports the value `excludeFromLists` in markdown frontmatter. This is inteded to be used for pages like "Contact" or "Search". If you set this value to true, the respective page:
- will not be displayed in the "Recent posts" and "All posts" lists
- will not include "Previous/Next post" navigation links
- will not be included in the site's RSS feed.
Argo comes with a pre-defined shortcode: including `{{< newtab href="https://some-site.com" >}}some text{{< /newtab >}}` in your markdown will render a link that opens a new tab.
The theme works with fallbacks and defaults a lot, e.g. if you do not set a logo, your website's title will be used instead.
## How to modify
Editing the theme is simple: you only have to recreate the path and file that you want to edit in your corresponding project directories and implement your desired changes there.
Here are three examples how to edit different aspects of the theme:
### Editing the Styling
Let's say you want to make changes to the stylesheet: in your project, create `assets/css/main.css`, then copy the CSS rules from the theme's stylesheet and add new rules or edit the existing ones for the changes you would like to have.
### Editing the HTML
You would like to display information like reading time and word count for each post. For this you will have to create `layouts/_default/single.html` in your project, then copy the content of the corresponding file from the theme into your own file and add the HTML and Go code for displaying this information. A block for displaying reading time and word count is already implemented in `layouts/partials/list/post-card.html`, here you would have to re-create these directories and this file in your project and simply remove the comment around the block.
### Editing JavaScript functions
In case you want to expand the results of the site-wide search, you should first look at `layouts/index.json`. That file generates data about all of your posts in JSON format. The JavaScript function for searching the site then uses that data to find matches with the user's query. So for expanding the data that will be searched by e.g. adding each post's entire content, you would have to add `"content" .Plain` to the dict in the `index.json` file first, then copy `assets/js/main.js` to your project and expand the filtering logic in the function `searchPosts()` accordingly.
|
