Skip to content

Commit 1972829

Browse files
joe-mccarthyjoe-mccarthy
committed
update readme
1 parent 98a519e commit 1972829

File tree

1 file changed

+259
-48
lines changed

1 file changed

+259
-48
lines changed

‎README.md‎

Lines changed: 259 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,303 @@
11
# Smigle Lite
22

3-
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/joe-mccarthy/smigle-lite/deploy-example.yml?branch=main&cacheSeconds=1)
4-
![Sonar Quality Gate](https://img.shields.io/sonar/quality_gate/joe-mccarthy_smigle-lite?server=https%3A%2F%2Fsonarcloud.io&cacheSeconds=1)
5-
![GitHub Release](https://img.shields.io/github/v/release/joe-mccarthy/smigle-lite?sort=semver&cacheSeconds=1)
6-
![GitHub commits since latest release](https://img.shields.io/github/commits-since/joe-mccarthy/smigle-lite/latest?cacheSeconds=1)
7-
![GitHub License](https://img.shields.io/github/license/joe-mccarthy/smigle-lite?cacheSeconds=1)
3+
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/joe-mccarthy/smigle-lite/deploy-example.yml?branch=main&cacheSeconds=1&style=for-the-badge)
4+
![Sonar Quality Gate](https://img.shields.io/sonar/quality_gate/joe-mccarthy_smigle-lite?server=https%3A%2F%2Fsonarcloud.io&cacheSeconds=1&style=for-the-badge)
5+
![GitHub Release](https://img.shields.io/github/v/release/joe-mccarthy/smigle-lite?sort=semver&cacheSeconds=1&style=for-the-badge)
6+
![GitHub commits since latest release](https://img.shields.io/github/commits-since/joe-mccarthy/smigle-lite/latest?cacheSeconds=1&style=for-the-badge)
7+
![GitHub License](https://img.shields.io/github/license/joe-mccarthy/smigle-lite?cacheSeconds=1&style=for-the-badge)
88

9-
My own site was using the [Smigle](https://gitlab.com/ian-s-mcb/smigle-hugo-theme) as I really like the concept of simplicity, lite weight with no javascript and tracking. However there were aspects that I didn't like. I found myself making far more CSS hacks than I would like. Therefore took the decision to create a new version of the theme with the changes included.
9+
## Overview
1010

11-
## Description
11+
Smigle Lite is a minimalist Hugo theme focused on simplicity, performance, and privacy. It was created as a streamlined alternative to the original [Smigle](https://gitlab.com/ian-s-mcb/smigle-hugo-theme) theme, removing unnecessary elements while maintaining the core principles of being lightweight with no JavaScript or tracking.
1212

13-
On the face of it, there isn't many changes from [Smigle](https://gitlab.com/ian-s-mcb/smigle-hugo-theme), however the changes I've made are as follows:
13+
### Core Principles
1414

15-
* Removed the need for a user profile image.
16-
* Removed the site tag line, I'm not cool enough for one of those.
17-
* Removed the time to read post.
18-
* Removed the word count of posts.
19-
* Stripped down the post meta data listings.
20-
* Updated the taxonomies pages to just be lists with a count, no additional styles.
21-
* Updated the footer to include a reference back to [Smigle](https://gitlab.com/ian-s-mcb/smigle-hugo-theme) and [smol](https://github.com/colorchestra/smol).
22-
* Various spacing changes and CSS tweaks to address the removal of elements.
15+
* **No JavaScript** - Pure HTML and CSS for maximum performance
16+
* **No Tracking** - No Google analytics, cookies, or any user tracking
17+
* **No External Dependencies** - No external fonts, comment sections, or CDN resources
18+
* **Minimal Design** - Focus on content without distractions
2319

24-
This theme still retains the concept of the previous two themes of which it's based:
20+
## Features
2521

26-
* No JavaScript
27-
* No Google spyware or tracking of any kind
28-
* No other external dependencies, embedded fonts or comment sections
22+
### Key Differences from Original Smigle
2923

30-
## Getting Started
24+
Smigle Lite streamlines the original theme by:
3125

32-
From the root of your site:
26+
* Removing the user profile image requirement
27+
* Eliminating the site tagline
28+
* Removing reading time estimates
29+
* Removing word count displays
30+
* Simplifying post metadata presentation
31+
* Redesigning taxonomy pages as simple lists with counts
32+
* Updating the footer with proper attributions
33+
* Various spacing improvements and CSS optimizations
34+
* Post Navigations
35+
* Recent Posts displayed on each post configurable in the config file
36+
37+
### Theme Structure
3338

34-
```bash
35-
git submodule add https://github.com/joe-mccarthy/smigle-lite themes/smigle-lite
3639
```
40+
smigle-lite/
41+
├── archetypes/ # Template files for new content
42+
├── assets/ # CSS and other asset files
43+
├── exampleSite/ # Demo site with example content
44+
├── i18n/ # Internationalization files
45+
├── layouts/ # Hugo template files
46+
└── static/ # Static files (images, etc.)
47+
```
48+
49+
## Installation
3750

38-
### Running the example-site
51+
### As a Git Submodule (Recommended)
3952

40-
To try out the theme prior to changing your site to use the theme, you can start up the example site within the theme.
53+
From the root of your Hugo site:
4154

4255
```bash
43-
git clone https://github.com/joe-mccarthy/smigle-lite
44-
cd example-site
45-
hugo server --source . --themesDir ../../ --theme smigle-lite
56+
git submodule add https://github.com/joe-mccarthy/smigle-lite themes/smigle-lite
4657
```
4758

48-
Open your web browser to [http://localhost:1313](http://localhost:1313) to view the demo of the theme.
59+
Then, update your site's configuration file to use the theme:
4960

50-
### Updating
61+
```yaml
62+
# config.yaml
63+
theme: smigle-lite
64+
```
5165
52-
From the root of your site:
66+
Or for TOML:
5367
54-
```bash
55-
git submodule foreach git pull origin main
68+
```toml
69+
# config.toml
70+
theme = "smigle-lite"
5671
```
5772

58-
### Run example site
73+
### Direct Download
74+
75+
1. Download the [latest release](https://github.com/joe-mccarthy/smigle-lite/releases/latest)
76+
2. Extract into your site's `themes` directory
77+
3. Update your site's configuration file as shown above
78+
79+
## Quick Start Guide
80+
81+
### Creating a New Site with Smigle Lite
5982

6083
```bash
84+
# Create a new Hugo site
6185
hugo new site mysite -f yaml
6286
cd mysite
87+
88+
# Add theme
6389
git init
6490
git submodule add https://github.com/joe-mccarthy/smigle-lite themes/smigle-lite
65-
# update config.yaml theme variable to be theme: smigle-lite
91+
92+
# Edit config.yaml to set theme: smigle-lite
93+
echo 'theme: smigle-lite' >> config.yaml
94+
95+
# Create a new post
96+
hugo new content/posts/my-first-post.md
97+
98+
# Start development server
6699
hugo server
67100
```
68101

69-
### Configuration
102+
### Running the Example Site
103+
104+
To see a demo of the theme:
105+
106+
```bash
107+
git clone https://github.com/joe-mccarthy/smigle-lite
108+
cd smigle-lite/exampleSite
109+
hugo server --themesDir ../..
110+
```
111+
112+
Then visit [http://localhost:1313](http://localhost:1313) in your browser.
113+
114+
## Configuration Reference
115+
116+
### Basic Configuration
117+
118+
```yaml
119+
# config.yaml
120+
baseURL: "https://example.com/"
121+
languageCode: "en-us"
122+
title: "My Smigle Lite Site"
123+
theme: "smigle-lite"
124+
125+
# Main menu configuration
126+
menu:
127+
main:
128+
- identifier: "home"
129+
name: "Home"
130+
url: "/"
131+
weight: 1
132+
- identifier: "posts"
133+
name: "Posts"
134+
url: "/posts/"
135+
weight: 2
136+
- identifier: "categories"
137+
name: "Categories"
138+
url: "/categories/"
139+
weight: 3
140+
- identifier: "tags"
141+
name: "Tags"
142+
url: "/tags/"
143+
weight: 4
144+
- identifier: "about"
145+
name: "About"
146+
url: "/about/"
147+
weight: 5
148+
```
149+
150+
### Theme Parameters
151+
152+
```yaml
153+
# Complete theme parameters
154+
params:
155+
# Latest posts section
156+
latest:
157+
enable: true # Enable/disable latest posts section
158+
count: 5 # Number of posts to display
159+
160+
# Date formats
161+
abbrDateFmt: "Jan 2" # Abbreviated date format (for lists)
162+
dateFmt: "January 2, 2006" # Long date format (for post meta)
163+
164+
# Social links in footer
165+
social:
166+
- name: "GitHub"
167+
url: "https://github.com/yourusername"
168+
- name: "Twitter"
169+
url: "https://twitter.com/yourusername"
170+
- name: "LinkedIn"
171+
url: "https://linkedin.com/in/yourusername"
172+
173+
# Content license (optional)
174+
license:
175+
name: "CC BY-SA 4.0"
176+
url: "https://creativecommons.org/licenses/by-sa/4.0/"
177+
178+
# Other options
179+
showTaxonomyLinks: true # Show categories and tags links in post meta
180+
favicon: "/favicon.ico" # Path to favicon (relative to static folder)
181+
```
182+
183+
## Customization
184+
185+
### Custom CSS
186+
187+
To add your own CSS customizations, create a file at `assets/css/custom.css` in your site root. This will be automatically included.
188+
189+
Example custom CSS:
190+
191+
```css
192+
/* assets/css/custom.css */
193+
body {
194+
font-family: 'Your Preferred Font', sans-serif;
195+
}
196+
197+
.site-header {
198+
background-color: #f0f0f0;
199+
}
200+
```
201+
202+
### Content Organization
203+
204+
Smigle Lite works best with the following content structure:
205+
206+
```
207+
content/
208+
├── posts/ # Blog posts
209+
├── pages/ # Static pages
210+
└── about/ # About page
211+
└── index.md
212+
```
213+
214+
### Front Matter Options
215+
216+
```yaml
217+
---
218+
title: "My Post Title"
219+
date: 2023-07-15T10:00:00-05:00
220+
draft: false
221+
categories: ["Technology"]
222+
tags: ["hugo", "tutorial"]
223+
summary: "Optional summary that will be displayed in lists"
224+
---
225+
```
226+
227+
## Advanced Usage
70228

71-
The example-site has a configuration that shows the following:
229+
### Custom Shortcodes
230+
231+
Smigle Lite supports all built-in Hugo shortcodes plus any you create in your site's `layouts/shortcodes` directory.
232+
233+
### Image Handling
234+
235+
For responsive images:
236+
237+
```markdown
238+
{{< figure src="/images/my-image.jpg" title="Image Title" alt="Image description" >}}
239+
```
240+
241+
### Taxonomies
242+
243+
Customize how taxonomies are displayed by editing your site's configuration:
244+
245+
```yaml
246+
taxonomies:
247+
category: categories
248+
tag: tags
249+
series: series
250+
```
72251

73-
* menu:main :- Example on how to set the menu items at the top of the site.
74-
* params:latest :- how to enable the latest posts at the bottom of post content, and the number of posts to show.
75-
params:abbrDateFmt :- This is the format for short date formats this is used within the /posts to show all posts by year.
76-
* params:dateFmt :- The format of the data shown in the post meta sections.
77-
* params:social :- List of links to be displayed in the footer of the site. This is a key value pair, with the __name__, and __url__ to navigate to.
78-
* params:license :- configures if a license is presented in the footer for the site contents. If no license do not include this configuration item. If there is a license then two sub items have to be added for the __name__ and __url__.
252+
## Updating the Theme
253+
254+
To update the theme when used as a git submodule:
255+
256+
```bash
257+
git submodule update --remote --merge
258+
```
259+
260+
Or for all submodules:
261+
262+
```bash
263+
git submodule foreach git pull origin main
264+
```
265+
266+
## Troubleshooting
267+
268+
### Common Issues
269+
270+
1. **Theme not loading**: Ensure your `config.yaml` has `theme: smigle-lite` (or `theme = "smigle-lite"` in TOML)
271+
272+
2. **Styling problems**: Check for CSS conflicts with custom CSS
273+
274+
3. **Missing content**: Verify your content is not marked as `draft: true` unless using the `--buildDrafts` flag
79275

80276
## Contributing
81277

82-
Have you found a bug or got an idea for a new feature? Feel free to use the [issue tracker](https://github.com/joe-mccarthy/smigle-lite/issues) to let me know. Or make directly a [pull request](https://github.com/joe-mccarthy/smigle-lite/pulls).
278+
Contributions to Smigle Lite are welcome! Please follow these steps:
279+
280+
1. Fork the repository
281+
2. Create a feature branch: `git checkout -b my-new-feature`
282+
3. Commit your changes: `git commit -am 'Add some feature'`
283+
4. Push to the branch: `git push origin my-new-feature`
284+
5. Submit a pull request
285+
286+
Before submitting your PR, please:
287+
- Ensure your code follows the project's style
288+
- Test your changes thoroughly
289+
- Update documentation as needed
83290

84291
## License
85292

86293
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
87294

88295
## Acknowledgements
89296

90-
* [Ian S. McBride](https://gitlab.com/ian-s-mcb) : The author and maintainer of the Hugo [Smigle](https://gitlab.com/ian-s-mcb/smigle-hugo-theme) Theme of which this theme is based upon.
91-
* [colorchestra](https://github.com/colorchestra) : Maintainer of [smol](https://github.com/colorchestra/smol) of which [Smigle](https://gitlab.com/ian-s-mcb/smigle-hugo-theme) was derived.
92-
* [Hugo](https://gohugo.io/) the static site generator that makes this all possible.
297+
* [Ian S. McBride](https://gitlab.com/ian-s-mcb) - Author and maintainer of the Hugo [Smigle](https://gitlab.com/ian-s-mcb/smigle-hugo-theme) theme
298+
* [colorchestra](https://github.com/colorchestra) - Maintainer of [smol](https://github.com/colorchestra/smol) theme
299+
* [Hugo](https://gohugo.io/) - The static site generator that makes this all possible
300+
301+
## Version History
302+
303+
See the [Releases](https://github.com/joe-mccarthy/smigle-lite/releases) page for the changelog and version history.

0 commit comments

Comments
 (0)