Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/esporo/bean

The new theme for @esporo.
https://github.com/esporo/bean

jekyll-theme jekyll-themes

Last synced: about 1 month ago
JSON representation

The new theme for @esporo.

Awesome Lists containing this project

README 

        
# Bean



[![Gem Version](https://badge.fury.io/rb/[email protected])](https://badge.fury.io/rb/jekyll-theme-bean)



Bean, named after [the best Spore creature](https://spore.fandom.com/wiki/Bean) out there, is a Jekyll theme made to use in both [Esporo](https://esporo.net) and [Simulando](https://simulando.net) fansites. It can be used freely by anyone.



Bean is colorful and customizable. You can change how it looks using CSS variables, you can add widgets to the sidebar or scripts easily.



## Features



- Make it yours with custom colors, typography and backgrounds.

- Automatic light and dark themes!

- Custom sidebar widgets and scripts with includes.

- Support for [pagination](https://github.com/jekyll/jekyll-paginate), [sitemap](https://github.com/jekyll/jekyll-sitemap), [SEO tags](https://github.com/jekyll/jekyll-seo-tag) and [archives](https://github.com/jekyll/jekyll-archives) out of the box.

- Translatable using [theme options](#configuration).



## Installation



### As a remote theme



You can use this theme with the [`jekyll-remote-theme`](https://github.com/benbalter/jekyll-remote-theme) plugin.



On your site repo, run:



```bash

$ bundle add jekyll-remote-theme

```



And add the following to your `_config.yml`:



```yaml

remote_theme: esporo/bean@latest



plugins:

  - jekyll-remote-theme

```



### As a gem-theme



You can also use this theme as a gem-based dependency to your Jekyll site.



Add this line to your Jekyll site's `Gemfile`:



```ruby

gem "bean"

```



And add this line to your Jekyll site's `_config.yml`:



```yaml

theme: bean

```



And then execute:



    $ bundle



Or install it yourself as:



    $ gem install bean



## Usage



Your theme can be configured using your `_config.yml`. You can also customize the theme, sidebar widgets and site-wide scripts by adding them to your Jekyll setup.



### Configuration



This is an example of a `_config.yml` with all the options available to Bean.



```yaml

title: Your awesome title

description: >-

  Your blog description. It will be shown at the bottom of your website.

tagline: A short-and-sweet tagline.



lang: en

logo: /path/to/your/logo.svg



# Build settings

permalink: "/:year/:month/:day/:title.html"

slug_mode: latin



# Theme Settings

bean:

  show_excerpts: true # this can also be set per-loop page.

  copyright_notice: >-

    Site built using [Bean](https://github.com/esporo/bean).

  date_formats:

    day: "%v"

    month: "%B, %Y"

    year: "%Y"

  translations:

    jump_to_navigation: "Go to navigation"

    jump_to_content: "Go to content"

    archive_date_title: "Posts from %s" # don't forget `%s`, it will be replaced by the date

    archive_tag_title: "Posts with the tag “%s”" # don't forget `%s`, it will be replaced by the tag name.

    archive_category_title: "Posts filed under “%s”" # don't forget `%s`, it will be replaced by the category name.

    post_tagged_with: "Tagged with:"

    blog_pagination_title: "Blog Pagination"

    blog_pagination_next_page: "Older posts"

    blog_pagination_prev_page: "Newer posts"

  

# Menus

main_menu:

  title: Navigate

  items:

    - label: Home

      path: /

    - label: About

      path: /about/

    - label: Bugs?

      path: https://github.com/esporo/bean/issues

    - label: Docs

      path: hhttps://github.com/esporo/bean?tab=readme-ov-file#readme



footer_menu:

  title: Socials

  items:

    - label: Discord

      path: https://discord.gg/

    - label: YouTube

      path: https://youtube.com/

    - label: Facebook

      path: https://www.facebook.com/

```



#### Plugins



Bean adds support for pagination, archives, feeds and SEO tags, so you can configure the settings following these plugins docs:



* [jekyll-paginate](https://jekyllrb.com/docs/pagination/)

* [jekyll-archives](https://github.com/jekyll/jekyll-archives/blob/master/docs/configuration.md)

* [jekyll-feed](https://github.com/jekyll/jekyll-feed?tab=readme-ov-file#usage)

* [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag/blob/master/docs/usage.md)

* [jekyll-sitemap](https://github.com/jekyll/jekyll-sitemap)



Please refer to the full [`_config.yml`](https://github.com/esporo/bean/blob/main/_config.yml) for plugin configurations.



#### Style Options



You can add a `theme.css` in your `/assets/css` directory to customize the style options of your site.



Just copy our [`theme.css`](https://github.com/esporo/bean/blob/main/assets/css/theme.css) and uncomment the lines of the variables you want to change, and you're good to go. Please note that background and color variables have different values for light and dark color schemes.



`theme.css` is also a good place to add custom style rules as well, since it's the last stylesheet called by your theme. It will overwrite any rules set by default.



You can also replace the fonts used in your theme by placing them in your `/assets/fonts` directory and declaring them on `/assets/fonts/fonts.css`.



### Menus



Bean has two menus available. One at the header and other at the bottom of your site. Both are set up in your `_config.yml`:



```yaml

main_menu:

  title: Navigate

  items:

    - label: Home

      path: /

    - label: About

      path: /about/

    - label: Bugs?

      path: https://github.com/esporo/bean/issues

    - label: Docs

      path: hhttps://github.com/esporo/bean?tab=readme-ov-file#readme



footer_menu:

  title: Socials

  items:

    - label: Discord

      path: https://discord.gg/

    - label: YouTube

      path: https://youtube.com/

    - label: GitHub

      path: https://github.com/

```



A menu title is used by screen reader software. It's strongly recommended that you add one to your menus.



### Includes



You can customize parts of the theme by adding includes to your repo.



There are three available includes for you to customize:



* `_includes/below-post.html`: will add content to your post page after the post structure. Useful for comments or notices.

* `_includes/widgets.html`: will add widgets to your blog sidebar. See [Sidebar](#sidebar) below.

* `_includes/scripts.html` will add add site-wide scripts like Disqus and analytics stuff at the end of the `` tag.



### Sidebar



Your blog sidebar can be customized by adding widgets to your `_includes/widgets.html`. The theme provides a default layout for widgets.



You can do something like this:



```html



{% assign widget_title = "My beautiful widget" %}



{% capture widget_content %}

  
This will be shown in my website sidebar! It's useful for a blogroll, useful links, etc.


{% endcapture %}



{% include blog/widget.html title=widget_title content=widget_content %}

```



You can as many widgets as you want, just repeat the process above.



The sidebar can be hidden in a page with the `page` layout. Just add it to your front-matter:



```yml

---

layout: page

title: About

hide_sidebar: true

---

```



### Post authors



Bean tries to bring up post author information from the following sources:



1. An `author` object in the front-matter of your post:

  ```yaml

  author:

    name: Will Wright

    url: https://example.com

  ```

2. Your `_data/authors.yml`.

  It may look like this:

  

  ```yaml

  will:

    name: Will Wright

    url: https://example.com

  ```

3. A `site.authors` or `site.author` object in your `_config.yml`.

  Something like this will do:

  

  ```yaml

  authors:

    will:

      name: Will Wright

      url: https://example.com

      lucy:

      name: Lucy Bradshaw

      url: https://example.net



  # or



  author:

    name: Will Wright

    url: "https://willwright.blog"

  ```



If none of these sources are available, Bean will just show the value of your `post.author` as it is.



## Contributing



Bug reports and pull requests are welcome on GitHub at https://github.com/esporo/bean.



Be aware that, as this theme is intended to be used by my own fansite, not every suggestion may be applied. You are free to fork it and change it to fit your needs!



## License



The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).