README.md


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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# Showcase theme for Hugo

![Latest Release](https://img.shields.io/github/tag/apvarun/showcase-hugo-theme.svg)
![Showcase hugo theme](https://img.shields.io/github/license/apvarun/showcase-hugo-theme)
![Hugo generator](https://img.shields.io/badge/generator-hugo-brightgreen)

Showcase is a minimal, single page theme for Hugo

![Preview](https://github.com/apvarun/showcase-hugo-theme/raw/main/images/screenshot.png)

![Preview Dark](https://github.com/apvarun/showcase-hugo-theme/raw/main/images/screenshot-dark.png)

Features:

- Auto-generated menu
- Responsive content
- Filtering content
- Social links
- Custom menu
- Darkmode

## Get the theme

Run from the root of your Hugo site:

```sh
git clone https://github.com/apvarun/showcase-hugo-theme.git themes/showcase
```

Alternatively, you can include this repository as a [git submodule](https://git-scm.com/docs/gitsubmodules). This makes it easier to update this theme if you have your Hugo site in git as well:

```sh
git submodule add https://github.com/apvarun/showcase-hugo-theme.git themes/showcase
```

## Preview the theme with example content

Showcase theme ships with an fully configured example site. For a quick preview:

Copy the `package.json` file from `themes/showcase` folder to your hugo website root folder, and run `npm install`.

```sh
cd themes/showcase/exampleSite/
hugo serve --themesDir ../..
```

Then visit `http://localhost:1313/` in your browser to view the example site.

## Configuring theme to a hugo website

1. Copy `package.json` and `package-lock.json` to the root folder of your the website
2. Run `npm install` to install required packages for theme
3. Run `npm i -g postcss-cli` to use PostCSS with Hugo build
4. Set `theme = 'showcase'` in config.toml
5. Run `npm start` to start your local server

Make sure to commit the above changes to your repository.

When deploying to services like Netlify or Vercel, use the following command for building your site:

```sh
npm i && hugo -D --gc
```

## Migrating to v1.3.0

Minimum Hugo Version: 0.69.0

- Copy the `package.json` file from `themes/showcase` folder to your hugo website root folder, and run `npm install`.

## Add content

The following explains how to add content to your Hugo site. You can find sample content in the `exampleSite/` folder.

### Structure:
    .
    ├── ...
    ├── projects       # Section Name
    │   ├── project1   # Project 1
    │   ├── project2   # Project 2
    │   └── _index     # (optional) Customize section name &
    │                  # default image for section contents
    └── ...


## Configure your site

From `exampleSite/`, copy `config.toml` to the root folder of your Hugo site and change the fields as you like. Helpful comments are provided.

## Menu

Menu in Showcase theme is auto-generated from the sections inside your content folder.

### Exclude Sections from Menu

It is possible to exclude sections from the auto-generated list. In order to exclude a section, create an `_index.md` file in that section and set the property `private` to `true`. Refer example [index file](https://github.com/apvarun/showcase-hugo-theme/blob/master/exampleSite/content/books/_index.md).

### Custom Menu

You can also add a custom menu item using the `config.toml` and disable auto-generated sections if not required. Refer config in [exampleSite](https://github.com/apvarun/showcase-hugo-theme/blob/master/exampleSite/config.toml)

## Dark mode

In order to enable darkmode toggle in your side, set the `params.darkMode` property to `true` in your `config.toml`.

## Google Analytics

Set `googleAnalytics` in `config.toml` to activate Hugo's [internal Google Analytics template](https://gohugo.io/templates/internal/#google-analytics).

## Used By

- [Madhu Akula](https://madhuakula.com/content/)
- [@cloudmiracle](http://cloud.vn/)

## Issues

If you have a question, please [open an issue](https://github.com/apvarun/showcase-hugo-theme/issues) for help and to help those who come after you. The more information you can provide, the better!

## Contributing

Contributions are welcome. For major changes, please open an issue first to discuss what you would like to change.

## License

Licensed under [MIT](LICENSE)

## Acknowledgements

[Madhu Akula](https://github.com/madhuakula)