Skip to content

Latest commit

 

History

History
731 lines (497 loc) · 36.5 KB

README.md

File metadata and controls

731 lines (497 loc) · 36.5 KB
Raw

Bilberry Hugo Theme

How to contribute

GitHub version Hugo Version Hugo Themes

Build GH-Pages Contributors License

Bilberry is a premium Hugo theme with many great features. This is an adaptation and further optimization of the Lingonberry WordPress theme by Anders Norén.

Here's a live demo site to see this theme in action.

Support and Discussions

Support for this theme is provided through the Issues and Discussions sections of the project. Please use the Issues section if you would like to report a defect or bug. For any other requests, use the Discussions section.

Please use the following guidelines if you want to start a discussion:

  • For any questions regarding a specific feature, or if you need help using or customizing the theme, use the Questions & Answers (Q&A) category.
  • To propose a new feature or any other improvements, use the Ideas category.
  • To showcase your blog or website powered by Bilberry theme, use the Show and tell category.
  • For any other inquiries, please use the General type discussion.

Table of Contents

Requirements

Hugo version >= 0.77.0 required; see this guide on how to install Hugo.
Only when using theme as Hugo module:
Git optional; download Git installer here

Quick Start

  • Create a new site:
hugo new site my-new-blog
  • Install the latest version of this theme:
cd my-new-blog/themes
git clone https://github.com/Lednerb/bilberry-hugo-theme.git

If you don't use Git, you can download this theme here and extract it manually into the themes folder. Make sure the folder containing the extracted theme is named bilberry-hugo-theme.

  • Copy example site content including the config.toml file:
cp -r bilberry-hugo-theme/exampleSite/* ../
  • Remove the default archetype:
cd ../
rm archetypes/default.md
  • Configure the necessary properties in the config.toml file. Then start the webserver and to publish your website:
hugo server

Important: Do NOT change the name of the bilberry-hugo-theme folder. Renaming this folder will break your site.

Also, check out this tutorial on how to build a Bilberry theme-based website using Hugo, GitHub, and Netlify.

Configuration

To customize your site according to your needs, simply edit the config.toml file in the site's root directory by adjusting the settings. All parameters that need to be configured are commented out or disabled.

Also, you can read this write-up on how to manage environment-specific settings for a Hugo-based website.

Features

Post Types

Bilberry theme comes with a set of predefined post types, namely article, audio, code, gallery, link, page, quote, status, and video where the article type is the default one.

To create a new content, use the hugo new command. Content can be created in two ways: a single page or a page bundle.

To create new content as a single page, you can use the following command:

hugo new <content-type>/my-single-page-content.md

Or, new page bundle content can be created as follows:

hugo new <content-type>/my-page-bundle-content/index.md

For example, you can create a new article as a single page and a new gallery as a page bundle using the following commands respectively:

hugo new article/my-single-page-article.md
hugo new gallery/my-page-bundle-gallery/index.md

The page post type is the only one that can be used in the top navigation bar. Pages can be ordered using the weight front matter variable, which should be set to a non-zero value. A page with a lower weight will be displayed first.

The page content can be a static page, such as an About page, or a link to another page, internal or external.

The link post type always links to an external site and can be used with or without a background image.

Top Navigation Bar

If you want to permanently display the top navigation bar with the search text field and page items, set the permanentTopNav parameter to true in the config.toml file.

Please note that the top navigation bar is minimized by default on mobile devices.

Algolia Search

Bilberry theme includes built-in content search via Algolia SAAS. You can see this in action on the demo site by clicking on "hamburger" and typing something in the search text field, such as "support."

Initial Setup

To enable and configure search functionality for your site, follow these steps:

  1. Register for a free Algolia Search account on https://www.algolia.com/.
  2. Add a New Application. You can choose the COMMUNITY plan.
  3. Switch over to Indices and create a new index.
  4. Switch over to API Keys and copy your Application ID, Search-Only API Key and chosen Index name to your config.toml file.
  5. Make sure that the algolia_search parameter is set to true.
  6. Follow instructions in the section Update Algolia Index and proceed to the next step.
  7. To complete the initial setup, go to the tab Configuration of your newly created indices, select the Facets in the section FILTERING AND FACETING and add the language attribute with the filter only modifier in the Attributes for faceting option. If, after adding the language attribute, the Unknown attribute error is shown, ignore it.

Update Algolia Index

You have to repeat this step every time you change a post or publish a new one to update the search index.

Execute the hugo command in the site's root directory to generate the index file.

Manual Upload
  1. Head over to the public/index.json file and copy its content.
  2. Login to your Algolia account, open your index and click at Add records manually.
  3. Paste the copied text from the index.json file.
  4. Verify in the Browse tab of your index that the index records were uploaded correctly.
  5. In case you have a multi-language setup, make sure that you repeat the steps above for all public/{LANG}/index.json files.
Automated Upload
  1. Switch to the algolia directory and install required dependencies by executing the following command:
cd algolia
npm install
  1. Run the data-upload.js from from the algolia directory as follows:
npm run data-upload -- -f ../public/index.json -a <algolia-app-id> -k <algolia-admin-api-key> -n <algolia-index-name>
  1. The algolia-admin-api-key argument, namely your Algolia account's Admin API Key, is used to create, update, and delete indices, and it should be kept secret.
  2. Add the -c or --clear-index option if you want to clear the corresponding Algolia index before starting a new upload.
  3. Login to your Algolia account and verify in the Browse tab of your index that the index records were uploaded correctly.
  4. In case you have a multi-language setup, make sure that you repeat the steps above for all public/{LANG}/index.json files.

Also, you can read this write-up on how to automate data upload to Algolia index if you host your Bilberry theme-based website on Netlify, or this write-up using GitHub Actions.

Keyboard Shortcuts

Type s to open the navigation bar and set focus to the search input field. To remove focus, press the Esc key.

Reposted Article/Duplicated Content

If you need to repost an article from another website or duplicate content on your site, you should link it to the original URL so it's correctly processed by SEO. To do so, define the original_url front matter variable in your post, for example:

original_url: "https://example.org/path/to/content"

Calculated Reading Time

To override the automatically calculated reading time for a post, you can use the readingTime front matter variable, for example:

readingTime: 7 # integer value in  minutes

Summary Splits

There are three options for how Hugo can generate summaries of content which will be used as a short version in summary views, such as a home page and tags or categories pages.

Automatic Summary Split

Using first 70 words of your content, Hugo automatically generates the summary followed by the Continue reading link.

Manual Summary Split

Add the <!--more--> summary divider to your content. Any content before the divider will be used by Hugo as a summary of that content. The generated summary will also be followed by the Continue reading link.

Front Matter Summary Split

To define a summary that differs from the text that starts your article, use the summary front matter variable, for example, summary: "Here goes my summary". This summary will also be followed by the Continue reading link.

No Summary Split

If you want to display the entire article without the Continue Reading link, set the noSummary variable to true in your content file.

Table of Contents (TOC)

To enable the automatic creation of a table of contents (TOC), set the toc front matter variable to true in your article. If the article's markdown contains appropriate headings, Hugo will generate a table of content at the beginning of the article.

By default, a TOC is generated if the content's word count is greater than 400. The tocMinWordCount parameter defines this value in the config.toml configuration file.

The headings that are taken into account for a TOC are from H2 (##) to H5 (#####) inclusive. Also, if you want to display a TOC at a specific point in your article, set the toc front matter variable to false, and use the toc shortcode like this:

{{< toc >}}

Series Taxonomy

In case you want to group some articles as a series, you have to add the series front matter variable to each article and set its value to the name of the series, for example, series: "My New Super Series".

The page at <site-base-url>/series/ will list all the series. To list all articles for a particular series within markdown, you can use the series shortcode with the series name in question, for instance:

{{< series "My New Super Series" >}}

Comments

To allow readers to comment under your articles, you can use either Commento, Disqus, Giscus, or Utterances.

Commento

Follow this guide if you want to use Commento Cloud Service which is not free of cost.

In case you want to use Self-hosting Commento, follow these instructions.

Then uncomment the commentoJsURL parameter in the config.toml file:

#[...]
[params]
    #[...]

    # Commento
    commentoJsURL = "http://localhost:8080/js/commento.js"

Disqus

To allow readers to leave comments under your articles, sign up for free on Disqus website. Then create a new site and set the disqusShortname parameter to your site's short name in the config.toml file:

#[...]
[params]
    #[...]

    # Disqus
    disqusShortname = "lednerb"

You can manage and moderate the comments either on your website or using the Disqus management panel.

Giscus

Follow instructions on Giscus website. Once you complete the prerequisites for your GitHub repository and select a discussion category, values for giscusRepositoryId and giscusCategoryId will be automatically generated. Then, in the config.toml file, set the giscus parameter to true and the properties mentioned above, respectively:

#[...]
[params]
    #[...]

    # Giscus
    giscus              = true
    giscusJsUrl         = "https://giscus.app/client.js"
    giscusRepository    = "Lednerb/bilberry-hugo-theme"
    giscusRepositoryId  = "R_kgDOGX153A" # generated by Giscus website
    giscusMapping       = "pathname"
    giscusCategory      = "General"
    giscusCategoryId    = "DIC_kwDOGX153M4B_2Vz" # generated by Giscus website
    giscusTheme         = "light"
    giscusReactions     = "1"
    giscusEmitMetadata  = "0"
    giscusLanguage      = "en"
    giscusCrossOrigin   = "anonymous"

Utterances

Follow instructions on Utterances website. Once you complete the prerequisites for your GitHub repository, set the utterances parameter to true in the config.toml file:

#[...]
[params]
    #[...]

    # Utterances
    utterances            = true
    utterancesJsUrl       = "https://utteranc.es/client.js"
    utterancesRepository  = "Lednerb/bilberry-hugo-theme"
    utterancesIssueTerm   = "pathname"
    utterancesLabel       = "Comment"
    utterancesTheme       = "github-light"
    utterancesCrossOrigin = "anonymous"

Responsive Design

Bilberry theme is optimized to look good on all devices, namely desktops, tablets and smartphones.

Automatic Image Resizing

Bilberry theme includes built-in automatic cropping and resizing only for featured and gallery images, activated by default. However, if you want to disable it, set the resizeImages parameter to false in the config.toml file. Also, this feature can be disabled at the post level by setting the resizeImages front matter variable to false.

For a featured image to be cropped and resized, it should be named featuredImage.* where the * is the image file extension, e.g., jpg, png, etc. Also, it should be placed within the page bundle in question, for example:

content
└── article
    └── my-post-with-featured-image
        ├── featuredImage.png
        └── index.md

NOTE: a featured image defined via the featuredImage front matter parameter will NOT be cropped and resized.

Image Modal Zoom

When you include an image that is larger than the content area, the image becomes interactive and a larger version can be opened in a lightbox.

MathJAX Markup

To enable the MathJAX markup support, set the enable_mathjax parameter to true in the config.toml file.

Disabled Javascript Support

Although this theme has a lot of features that only work with enabled JavaScript, it also fully supports disabled JavaScript. Disabled Javascript will not break any styling or essential functionalities of your website.

You can test the behavior of the demo site by disabling JavaScript in your browser.

Video

The following video hosting providers are supported: YouTube, Vimeo, Prezi, Bilibili, and PeerTube. Videos in the MP4 format, either stored externally or within the site's static folder, are also supported. There are two options to display video embeds.

The first option is to use a post of the video type. Use the following command to create your video post:

hugo new video/<post-name>.md

Then set the appropriate front matter variable while removing the others:

youtube: "<youtube-video-id>" # https://www.youtube.com/watch?v=M7IjJiZUutk -> "M7IjJiZUutk"
vimeo: "<vimeo-video-id>" # https://vimeo.com/239830182 -> "239830182"
prezi: "<prezi-video-id>" # https://prezi.com/v/5z9shnq7jzxs/what-to-study/ -> "5z9shnq7jzxs"
bilibili: "<bilibili-video-id>" # https://www.bilibili.com/video/BV1Sx411T7QQ -> "BV1Sx411T7QQ"
peertube: "<peertube-video-id>" # https://vids.tekdmn.me/w/w7WGHX7Lb6mCrbrpF3Xb8V (entire URL)
mp4video: "<video-file-url>" # location of video file (only mp4)
mp4videoImage: "<image-video-file-url>" # location of poster image

For example, if an MP4 video and its image are stored in the static folder, you can set corresponding front matter variables as follows:

mp4video: "/<video-file-name>.mp4"
mp4videoImage: "/<image-video-file-name>.png"

The second option is to use the video shortcode within markdown content in a post of the article type as follows:

<!-- YouTube -->

{{< video type="youtube" id="<youtube-video-id>" >}}

<!-- Vimeo -->

{{< video type="vimeo" id="<vimeo-video-id>" >}}

<!-- Prezi -->

{{< video type="prezi" id="<prezi-video-id>" >}}

<!-- bilibili -->

{{< video type="bilibili" id="<bilibili-video-id>" >}}

<!-- PeerTube -->

{{< video type="peertube" id="<peertube-video-id>" >}}

<!-- MP4 external -->

{{< video type="mp4" url="<video-file-url>" imageUrl="<image-video-file-url>" >}}

<!-- MP4 in site's static folder -->

{{< video type="mp4" url="/<video-file-name>.mp4" imageUrl="/<image-video-file-name>.png" >}}

PeerTube Configuration

Because there is no one PeerTube site, you need to indicate which ones your videos use, meaning you can't use just the video ID. Instead, copy in the entire watch URL, and it'll be transformed into the correct embed URL to use.

There is an instance finder if you want to start hosting your videos on PeerTube but don't know which instance to join.

Audio

The following audio streaming providers are supported: Mixcloud, SoundCloud, Spotify, and TuneIn. Audio files in the Ogg, MP3, or WAV formats, either stored externally or within the site's static folder, are also supported. There are two options to display audio embeds.

The first option is to use a post of the audio type. Use the following command to create your audio post:

hugo new audio/<post-name>.md

Then set the appropriate front matter variable while removing the others:

spotify: "<spotify-track-id>" # https://open.spotify.com/track/3W2lz1sg6m4sEzjmoTjmdE?si=0659fd12179840dd --> 3W2lz1sg6m4sEzjmoTjmdE
soundcloud: "<soundcloud-track-url>" # https://soundcloud.com/lightbooks/alchemist-08-new-world-order-snip
tunein: "<tunein-track-id>" # https://tunein.com/embed/player/t117894382/" --> t117894382
mixcloud: "<mixcloud-track-id>" # https://www.mixcloud.com/scienceforthepeople/445-ai-ant-intelligence/ --> scienceforthepeople/445-ai-ant-intelligence
audiofile: "<audio-file-url>" # location of audio file (only ogg, mp3, or wav formats)

For example, if an MP3 audio file is stored in the static folder, you can set the audiofile front matter variable as follows:

audiofile: "/<audio-file-name>.mp3"

The second option is to use the audio shortcode within markdown content in a post of the article type as follows:

<!-- Mixcloud -->

{{< audio type="mixcloud" id="<mixcloud-track-id>" >}}

<!-- SoundCloud -->

{{< audio type="soundcloud" id="<soundcloud-track-url>" >}}

<!-- Spotify -->

{{< audio type="spotify" id="<spotify-track-id>" >}}

<!-- TuneIn -->

{{< audio type="tunein" id="<tunein-track-id>" >}}

<!-- MP3 external -->

{{< audio type="audiofile" url="<audio-file-url>" >}}

<!-- MP3 in site's static folder -->

{{< audio type="audiofile" url="/<audio-file-name>.mp3" >}}

Raw HTML

If you want to include raw HTML in your markdown content, set the unsafe setting in the config.toml file to true:

[markup.goldmark]
  [markup.goldmark.renderer]
    unsafe = true

Favicons

To add favicons, proceed with the following steps:

  1. Visit https://realfavicongenerator.net/ website, and generate favicons according to your needs.
  2. Copy and paste the generated files into your site's /static folder.
  3. Edit the /layouts/partials/favicon.html file, then copy and paste the HTML code from the generated instruction.

Important: You have to follow the Quick Start instructions or manually copy the /layouts/partials/favicon.html file from the theme to your site's /layouts directory.

Also, check out this tutorial on how to add favicons to Bilberry theme-based website.

Custom 404 Page

To customize your 404 page, copy the themes/bilberry-hugo-theme/layouts/404.html file to your site's layouts/404.html and edit the file according to your needs, for example, change the message, icon class etc.

Archive Page

The archive page will be available at <site-base-url>/archive/ as soon as you copy the themes/bilberry-hugo-theme/exampleSite/content/archive.md file to content directory of your site. By default, the published content is grouped by year. To group the content by year and month, set the archiveDateGrouping parameter to the 2006-01 value.

To display the archive link in the footer, set the showArchive parameter to true.

To add the archive link to the top navigation bar, create a new page with the following command:

hugo new page/archive.md

Then, in the newly created content/page/archive.md file, set the link front matter variable to the /archive/ value and completely remove the target variable.

Custom Post Types

With Bilberry theme, you can create new post types easily. For example, suppose you want to create a new type named book. Then you should do the following:

  1. Copy the default themes/bilberry-hugo-theme/layouts/partials/content-type/article.html to your site's layouts/partials/content-type/ folder.
  2. Rename the file to your custom post type, namely book.html.
  3. Customize the newly created file, for instance, change the icon in the bubble to fa-book that is available on Font Awesome Icon website:
<i class="fas fa-fw fa-book"></i>
  1. To create new posts, use the book post type prefix:
hugo new book/my-favorite-book.md`

If you want to use custom front matter variables, create a book.md archetype in your site's archetypes/ directory.

External Images

If you would like to use external images, such as those stored on another server or in the cloud, as a featured image for your article or in the gallery post type, you can use them by setting the appropriate front matter variables with the full-path URL values:

# /content/article/my-external-featured-image-post.md

featuredImage: "https://example.org/images/my-image.jpg"
# /content/gallery/my-external-gallery-post.md

gallery: [
"https://example.org/images/gallery-image1.jpg",
"https://example.org/images/gallery-image2.jpg",
"https://example.org/images/gallery-image3.jpg"
]

Individual Posts Customization

You can customize your posts as follows:

  1. To exclude posts from your blog's index but still show up in categories, add excludeFromIndex: true to your post's front matter.

  2. To pin one or more posts to the top of the index page, uncomment the pinnedPost parameter in the config.toml file. Then set its value to the post's relative URL, for example, /article/installing-bilberry-theme/. When pinning multiple posts, the relative URL values should be separated by a comma. The pinOnlyToFirstPage parameter allows you to choose whether to display pinned posts on the index page only or on all pages.

  3. A custom icon can be declared per post, by specifying a font-awesome icon in the post's front matter, such as icon: fa-thumb-tack for a pinned post.

  4. If you want to change the default post types(e.g., replace the pencil icon for the article post type another one) copy the original content type file to your site's layouts/partials/content-type/ directory and edit it there. Otherwise, your changes will be overwritten when you update the theme to the latest version.

Custom Colors and Fonts

Bilberry uses SCSS for styling and NPM with Laravel Mix for the dependency management.

To change any colors or fonts, you have to follow these steps:

  1. In your site's cd themes/bilberry-hugo-theme directory, execute npm install.
  2. Modify the assets/sass/_variables.scss file to customize your colors. If you want to change the header's color, only edit the $base-color variable.
  3. Use npm run dev for development and preview purposes and npm run production when you're done with the changes.

CSS and JS modules

This theme supports hot-swappable CSS and JavaScript extensions. Modules can be specified using the (css|js)_modules list parameter. Modules can be specified either relative to the static directory (e.g. exampleSite/static/css/custom.css) or as a URL.

Modules are imported in the order they appear in the list, and immediately after the default Bilberry CSS and JS files are imported.

Add Cookie Disclaimer

You can use the cookie consent solution to add cookie consent information by loading the needed resources as external CSS and JS modules.

Use the configurator on the cookie consent website to generate the required initialization code and add it to a local static/init-cookieconsent.js file, for example:

// https://cookieconsent.insites.com/download/#
window.addEventListener("load", function () {
  window.cookieconsent.initialise({
    palette: {
      popup: {
        background: "#cc0033",
      },
      button: {
        background: "#fff",
      },
    },
  });
});

Then you only need to modify the config.toml file to load the local init script and the libraries. You can either download the files and put them in your site's /static directory or reference them directly using a CDN. Storing these files on your website reduces external dependencies, increases privacy, and allows you to develop your website in an offline environment.

css_modules = ["..", "//cdnjs.cloudflare.com/ajax/libs/cookieconsent2/3.1.0/cookieconsent.min.css"]
js_modules = ["..", "//cdnjs.cloudflare.com/ajax/libs/cookieconsent2/3.1.0/cookieconsent.min.js", "init-cookieconsent.js"]

Translations

Bilberry theme has built-in support for multi-language sites, and currently supports translations for more than 20 languages.

Feel free to submit a request for a new language translation or improve existing ones!

Credits

Bilberry theme was inspired by the WordPress theme Lingonberry created by Anders Norén.

Bilberry is a theme for the great HUGO static site generator.

Special thank-you goes to @Ipstenu for his help in this thread that helped to create the index.json for the Algolia index.

Contributors

Many thanks go to these wonderful people (emoji key):


Sascha Brendel
💬 📝 💻 🎨 📖 🌍
Anna Brendel
🤔 🌍
Givi Khojanashvili
💻
Chung Tran Anh
💻 🌍
Minke Zhang
💻

Pavel Kanyshev
💻 🌍
Marcel Kraus
💻
Nick Busey
💻
lkorzen
🌍
Chris Stayte
🐛

Dmitry Matrosov
💻
Marc-Antoine
💻 🐛
Nina Zakharenko
💻 🐛 📖
Nisarga
💻
Pablo Domingo Rojo
💻

Rob Baruch
💻
Taoshi
🌍
nonumeros
💻
Marcelo Gonçalves
🌍
Dávid Sárkány
🌍

meonamz
🌍
Hamza Yusuf Çakır
🌍
Niclas Roßberger
💻 🐛 🚧
Igor Baiborodine
💻 🐛 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

License

The Bilberry Hugo theme is licensed under the MIT license.