diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 257 |
1 files changed, 199 insertions, 58 deletions
@@ -1,86 +1,227 @@ -# Hugo ʕ•ᴥ•ʔ Bear Blog  +# ᕦʕ •ᴥ•ʔᕤ Bear Cub -🧸 A [Hugo](https://gohugo.io/)-theme based on [Bear Blog](https://bearblog.dev). +[](https://github.com/clente/hugo-bearcub/actions/workflows/gh-pages.yml) +[](https://github.com/clente/hugo-bearcub/blob/main/LICENSE) -> Free, no-nonsense, super-fast blogging. +## Overview -## Demo +🐻 A lightweight [Hugo](https://gohugo.io/) theme based on [Bear +Blog](https://bearblog.dev) and [Hugo Bear +Blog](https://github.com/janraasch/hugo-bearblog). -For a current & working demo of this theme, please check out https://janraasch.github.io/hugo-bearblog/ 🎯. - -## Screenshots - -⬜️ [Light][light-screenshot] - -⬛️ [Dark][dark-screenshot] - -When the user's browser is running »dark mode«, the dark color scheme will be used automatically. The default is the light/white color scheme. Check out the [`style.html`](https://github.com/janraasch/hugo-bearblog/blob/master/layouts/partials/style.html)-file for the implementation. +**Bear Cub** takes care of speed and optimization, so you can focus on writing +good content. It is free, multilingual, optimized for search engines, +no-nonsense, responsive, light, and fast. Really fast. ## Installation -If you already have a Hugo site on your machine, you can simply add this theme via +Follow Hugo's [quick start](https://gohugo.io/getting-started/quick-start/) to +create an empty website and then clone **Bear Cub** into the themes directory as +a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules): -```bash -git submodule add https://github.com/janraasch/hugo-bearblog.git themes/hugo-bearblog +```sh +git submodule add https://github.com/clente/hugo-bearcub themes/hugo-bearcub ``` -Then, adjust the `hugo.toml` as detailed below. +To finish off, append a line to the site configuration file: -For more information, read the official [setup guide][hugo-setup-guide] of Hugo. +```sh +echo 'theme = "hugo-bearcub"' >> hugo.toml +``` -## Adjust configuration / hugo.toml +## Features -Please check out the [hugo.toml](https://github.com/janraasch/hugo-bearblog/blob/master/exampleSite/hugo.toml) included in the [exampleSite](https://github.com/janraasch/hugo-bearblog/tree/master/exampleSite) of this theme. +Like [Bear Blog](https://bearblog.dev), this theme: +- Is free and open source +- Looks great on any device +- Makes tiny (~5kb), optimized, and awesome pages +- Has no trackers, ads, or scripts +- Automatically generates an RSS feed -## Content & structure +But that's not all! **Bear Cub** is also... -### Starting fresh +### Accessible -If you are starting fresh, simply copy over the contents of the `exampleSite`-directory included in this theme to your source directory. That should give you a good idea about how things work, and then you can go on from there to make the site your own. +**Bear Cub** has a few accessibility upgrades when compared to its predecessors. +The color palette has been overhauled to make sure everything is +[readable](https://web.dev/color-and-contrast-accessibility/) for users with low +vision impairments or color deficiencies, and some interactive elements were +made bigger to facilitate [clicking](https://web.dev/accessible-tap-targets/) +for users with a motor impairment. -### Adding / editing content +These small changes mean that **Bear Cub** passes Google's [PageSpeed +test](https://pagespeed.web.dev/report?url=https%3A%2F%2Fclente.github.io%2Fhugo-bearcub%2F) +with flying colors. -#### Index-Page + -The contents of the `index`-page may be changed by editing your `content/_index.md`-file. +### Secure -#### Page +[**Bear Cub**'s demo](https://clente.github.io/hugo-bearcub/) is hosted on GitHub +and therefore I'm not in control of its [Content Security +Policy](https://infosec.mozilla.org/guidelines/web_security#content-security-policy). +However, the theme itself was made with security in mind: there are no inline +styles and it uses no JavaScript at all. -You can add **a new page** via running +If you want to improve your [Mozilla +Observatory](https://observatory.mozilla.org/) score even further, you should be +able to simply add a few headers to your hosting service's configuration (e.g. +[Netlify](https://docs.netlify.com/routing/headers/) or [Cloudflare +Pages](https://developers.cloudflare.com/pages/platform/headers/)) and never +have to think about it again. My `_headers` file, for example, looks like this: -```bash -hugo new my-new-page.md ``` - -#### Blog-Post - -You can add **a new blog-post** via running - -```bash -hugo new blog/my-new-post.md +/* + X-Content-Type-Options: nosniff + Strict-Transport-Security: "max-age=31536000; includeSubDomains; preload" env=HTTPS + Cache-Control: max-age=31536000, public + X-Frame-Options: deny + Referrer-Policy: no-referrer + Feature-Policy: microphone 'none'; payment 'none'; geolocation 'none'; midi 'none'; sync-xhr 'none'; camera 'none'; magnetometer 'none'; gyroscope 'none' + Content-Security-Policy: default-src 'none'; manifest-src 'self'; font-src 'self'; img-src 'self'; style-src 'self'; form-action 'none'; frame-ancestors 'none'; base-uri 'none' + X-XSS-Protection: 1; mode=block ``` -### Adding your branding / colors / css - -Add a `custom_head.html`-file to your `layouts/partials`-directory. In there you may add a `<style>`-tag, *or* you may add a `<link>`-tag referencing your own `custom.css` (in case you prefer to have a separate `.css`-file). Check out the [`style.html`](https://github.com/janraasch/hugo-bearblog/blob/master/layouts/partials/style.html)-file to find out which CSS-styles are applied by default. - -## Issues / Feedback / Contributing -Please use [GitHub issues](https://github.com/janraasch/hugo-bearblog/issues) and [Pull Requests](https://github.com/janraasch/hugo-bearblog/pulls). - -## Development -Run the `exampleSite` locally via - -```bash -hugo server --source ./exampleSite --themesDir ../.. +### Multilingual + +If you need to write a blog that supports more than one language, **Bear Cub** +has you covered! Check out the demo's [`hugo.toml` +file](https://github.com/clente/hugo-bearcub/blob/main/exampleSite/hugo.toml) +for a sample of how you can setup multilingual support. + +By default, the theme creates a translation button that gets disabled when the +current page is only available in any other language. You can also choose to +hide this button (instead of disabling it) by setting `hideUntranslated = +false`. + +### More + +Every once in a while, as I keep using **Bear Cub**, I notice that there is some +functionality missing. Currently, these are the "advanced features" that I have +already implemented: + +- Full-text RSS feed: an enhanced RSS feed template that includes the (properly + encoded) full content of your posts in the feed itself. +- Static content: you can create empty blog entries that act as links to static + files by including `link: "{url}"` in a post's [front + matter](https://gohugo.io/content-management/front-matter/). You can also add + `render: false` to your [build + options](https://gohugo.io/content-management/build-options/#readout) to avoid + rendering blank posts. +- Skip link: a "skip to main content" link that is temporarily invisible, but + can be focused by people who need a keyboard to navigate the web (see [PR + #5](https://github.com/clente/hugo-bearcub/pull/5) by + [@2kool4idkwhat](https://github.com/2kool4idkwhat) for more information). +- Reply by email: if you supply an email address, the theme creates a "Reply to + this post by email" button at the end of every post (see Kev Quirk's [original + implementation](https://kevquirk.com/adding-the-post-title-to-my-reply-by-email-button)). +- Single-use CSS (EXPERIMENTAL): you can add some styles to a single page by + writing the CSS you need in `assets/{custom_css}.css` and then including + `style: "{custom_css}.css"` in the [front + matter](https://gohugo.io/content-management/front-matter/) of said page. +- Conditional CSS (EXPERIMENTAL): since **Bear Cub** does syntax highlighting + without inline styles (see `hugo.toml` for more information), it only load its + `syntax.css` if, and only if, a code block is actually present in the current + page. +- Dynamic social card generation (EXPERIMENTAL): if you don't add preview images + to a post, this template will generate one based on the title. You can see an + example below. + + + +## Configuration + +**Bear Cub** can be customized with a `hugo.toml` file. Check out the +[configuration](https://github.com/clente/hugo-bearcub/blob/main/exampleSite/hugo.toml) +of the [demo](https://clente.github.io/hugo-bearcub/) for more information. + +```toml +# Basic config +baseURL = "https://example.com" +theme = "hugo-bearcub" +copyright = "John Doe (CC BY 4.0)" +defaultContentLanguage = "en" + +# Generate a nice robots.txt for SEO +enableRobotsTXT = true + +# Setup syntax highlighting without inline styles. For more information about +# why you'd want to avoid inline styles, see +# https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src#unsafe_inline_styles +[markup] + [markup.highlight] + lineNos = true + lineNumbersInTable = false + # This allows Bear Cub to use a variation of Dracula that is more accessible + # to people with poor eyesight. For more information about color contrast + # and accessibility, see https://web.dev/color-and-contrast-accessibility/ + noClasses = false + +# Multilingual mode config. More for information about how to setup translation, +# see https://gohugo.io/content-management/multilingual/ +[languages] + [languages.en] + title = "Bear Cub" + languageName = "en-US 🇺🇸" + LanguageCode = "en-US" + contentDir = "content" + [languages.en.params] + madeWith = "Made with [Bear Cub](https://github.com/clente/hugo-bearcub)" + [languages.pt] + title = "Bear Cub" + languageName = "pt-BR 🇧🇷" + LanguageCode = "pt-BR" + contentDir = "content.pt" + [languages.pt.params] + madeWith = "Feito com [Bear Cub](https://github.com/clente/hugo-bearcub)" + +[params] + # The description of your website + description = "Bear Cub Demo" + + # The path to your favicon + favicon = "images/favicon.png" + + # These images will show up when services want to generate a preview of a link + # to your site. Ignored if `generateSocialCard = true`. For more information + # about previews, see https://gohugo.io/templates/internal#twitter-cards and + # https://gohugo.io/templates/internal#open-graph + images = ["images/share.webp"] + + # This title is used as the site_name on the Hugo's internal opengraph + # structured data template + title = "Bear Cub" + + # Dates are displayed following the format below. For more information about + # formatting, see https://gohugo.io/functions/format/ + dateFormat = "2006-01-02" + + # If your blog is multilingual but you haven't translated a page, this theme + # will create a disabled link. By setting `hideUntranslated` to true, you can + # have the theme simply not show any link + hideUntranslated = false + + # (EXPERIMENTAL) This theme is capable of dynamically generating social cards + # for posts that don't have `images` defined in their front matter; By setting + # `generateSocialCard` to false, you can prevent this behavior. For more + # information see layouts/partials/social_card.html + generateSocialCard = true + + # Social media. Delete any item you aren't using to make sure it won't show up + # in your website's metadata. + [params.social] + twitter = "example" # Twitter handle (without '@') + facebook_admin = "0000000000" # Facebook Page Admin ID + + # Author metadata. This is mostly used for the RSS feed of your site, but the + # email is also added to the footer of each post + [params.author] + name = "John Doe" # Your name as shown in the RSS feed metadata + email = "me@example.com" # Added to the footer so readers can reply to posts ``` -## Special Thanks 🎁 - -A special thank you goes out to [Herman](https://herman.bearblog.dev), for creating the original [ʕ•ᴥ•ʔ Bear Blog](https://bearblog.dev/). - -## License -[MIT License](http://en.wikipedia.org/wiki/MIT_License) © [Jan Raasch](https://www.janraasch.com) +## Contributing -[hugo-setup-guide]: https://gohugo.io/getting-started/installing -[light-screenshot]: https://raw.githubusercontent.com/janraasch/hugo-bearblog/master/images/screenshot.png -[dark-screenshot]: https://raw.githubusercontent.com/janraasch/hugo-bearblog/master/images/screenshot-dark.png +If you come across any problems while using **Bear Cub**, you can file an +[issue](https://github.com/clente/hugo-bearcub/issues) or create a [pull +request](https://github.com/clente/hugo-bearcub/pulls). |