binario/README.md

229 lines
7.8 KiB
Markdown
Raw Normal View History

2018-04-27 07:08:35 +00:00
# Binario [WIP]
2018-04-25 18:30:37 +00:00
**Binario** is a responsive card-based & code-light Hugo theme.
2018-11-26 19:10:09 +00:00
**[Demo](https://binario.netlify.com/)**
2018-04-26 18:39:01 +00:00
![Binario theme screenshot](https://github.com/vimux/binario/blob/master/images/tn.png)
2018-04-25 18:30:37 +00:00
**Features:**
* Responsive
* Card-based list layout
2018-05-28 06:29:46 +00:00
* Internal Hugo templates for Open Graph and Twitter Cards meta data, Google Analytics, and Disqus comments
* Table of contents
2018-05-25 14:35:12 +00:00
* Related content
2018-05-27 12:01:09 +00:00
* MathJax
2018-04-25 18:30:37 +00:00
## Installation
*First of all, you will need to [install Hugo](https://gohugo.io/getting-started/quick-start/#step-1-install-hugo) and [create new site](https://gohugo.io/getting-started/quick-start/#step-2-create-a-new-site).* After that, you ready to install **Binario**.
2019-01-14 13:08:53 +00:00
There are three different ways you can install **Binario**. Choose one of the installation methods listed below and follow the instructions.
- **A**. [Git submodule (**Recommended**)](#step-1a-git-submodule-recommended)
- **B**. [Git clone](#step-1b-git-clone)
- **C**. [Download ZIP and manual install](#step-1c-download-zip-and-manual-install)
*For more information read the [Install and Use Themes](https://gohugo.io/themes/installing-and-using-themes/)*
### 1A. Git submodule (Recommended)
In your Hugo site directory, run:
```
2019-01-14 13:08:53 +00:00
git submodule add https://github.com/vimux/binario themes/binario
```
Next, edit your `config.toml` configuration file and add parameter:
```
theme = "binario"
```
*You can [read the GitHub documentation for submodules](https://github.com/blog/2104-working-with-submodules) or those found on [Git's website](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for more information*
### 1B. Git clone
In your Hugo site directory, run:
```
2019-01-14 13:08:53 +00:00
git clone https://github.com/vimux/binario themes/binario
```
Next, edit your `config.toml` configuration file and add parameter:
```
theme = "binario"
```
### 1C. Download ZIP and manual install
[Download ZIP](https://github.com/vimux/binario/archive/master.zip) and extract to the `themes/binario`
Next, edit your `config.toml` configuration file and add parameter:
```
theme = "binario"
```
2019-01-14 13:08:53 +00:00
***
After that, you can run your site in Hugo server mode:
```
hugo server
```
After you make sure that **Binario** works, you may start customizing the theme. You can change [number of columns](#columns), activate [footer social icons](#footer-social-icons) & [share buttons](#share-buttons) and much more.
2018-04-27 07:08:35 +00:00
## Configuration
2019-01-14 13:08:53 +00:00
Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the site root) as the default site config file. Here is Binario configuration example in TOML with theme-specific config params:
2018-04-27 07:08:35 +00:00
### Config.toml example
```toml
baseurl = "/"
2018-05-28 06:29:46 +00:00
title = "Binario"
2018-04-27 07:08:35 +00:00
languageCode = "en-us"
paginate = "10" # Number of posts per page
theme = "binario"
disqusShortname = "" # Enable comments by entering your Disqus shortname
googleAnalytics = "" # Enable Google Analytics by entering your tracking id
2018-11-18 16:00:23 +00:00
[Author] # Used in authorbox
name = "John Doe"
bio = "John Doe's true identity is unknown. Maybe he is a successful blogger or writer."
avatar = "img/avatar.png"
2018-04-27 07:08:35 +00:00
[Params]
2018-07-10 12:50:06 +00:00
description = "Responsive card-based & code-light Hugo theme" # Description of your site. Used in meta description
2019-01-03 15:23:18 +00:00
copyright = "Binario" # Copyright holder, otherwise will use .Site.Title
2018-07-10 12:50:06 +00:00
opengraph = true # Enable OpenGraph if true
twitter_cards = true # Enable Twitter Cards if true
2019-01-14 13:08:53 +00:00
columns = 2 # Set the number of cards columns. Possible values: 1, 2, 3
2018-07-10 12:50:06 +00:00
mainSections = ["post"] # Set main page sections
2018-11-15 19:21:34 +00:00
post_meta = ["date", "categories"] # Enable post meta fields in given order
dateFormat = "January 02, 2006" # Change the format of dates
2018-11-18 16:00:23 +00:00
authorbox = true # Show authorbox at bottom of single pages if true
2018-07-10 12:50:06 +00:00
toc = true # Enable Table of Contents for all site pages
tocOpen = true # Open Table of Contents block. Optional
comments = true # Enable comments for all site pages
related = true # Enable Related content for single pages
relatedMax = 5 # Set the maximum number of posts that can be displayed in related block. Optional
2018-07-10 12:50:06 +00:00
mathjax = true # Enable MathJax for all site pages
2018-08-08 18:30:27 +00:00
mathjaxPath = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" # Specify MathJax path. Optional
2018-07-10 12:50:06 +00:00
mathjaxConfig = "TeX-AMS-MML_HTMLorMML" # Specify MathJax config. Optional
2019-01-14 14:26:42 +00:00
hideNoPostsWarning = false # Don't show no posts empty state warning in main page, if true
[Params.Social]
2018-07-10 12:50:06 +00:00
email = "example@example.com"
facebook = "username"
twitter = "username"
telegram = "username"
instagram = "username"
pinterest = "username"
vk = "username"
linkedin = "username"
github = "username"
gitlab = "username"
stackoverflow = "numberid"
mastodon = "username"
medium = "username"
2018-06-11 18:41:16 +00:00
[Params.Share] # Post Share block
2018-07-10 12:50:06 +00:00
facebook = true
twitter = true
reddit = true
telegram = true
linkedin = true
vk = true
pocket = true
2018-06-11 18:41:16 +00:00
# Web App Manifest settings
# https://www.w3.org/TR/appmanifest/
# https://developers.google.com/web/fundamentals/web-app-manifest/
[Params.Manifest]
2018-07-10 12:50:06 +00:00
name = "Binario"
shortName = "Binario"
display = "browser"
backgroundColor = "#2a2a2a"
themeColor = "#1b1b1b"
description = "Responsive card-based & code-light Hugo theme"
orientation = "portrait"
startUrl = "/"
scope = "/"
[outputFormats]
[outputFormats.MANIFEST]
mediaType = "application/json"
baseName = "manifest"
isPlainText = true
notAlternative = true
[outputs]
2018-07-31 17:40:03 +00:00
home = ["HTML", "RSS", "MANIFEST"]
2018-04-27 07:08:35 +00:00
```
2019-01-14 13:08:53 +00:00
For more information about Hugo configuration files and all common configuration settings, please read [Configure Hugo](https://gohugo.io/getting-started/configuration) from Hugo official documentation.
2018-11-26 19:10:09 +00:00
### Front Matter example
2019-01-14 13:08:53 +00:00
Hugo supports three formats for front matter: `yaml`, `toml` and `json`. Here is Front Matter example in YAML:
2018-11-26 19:10:09 +00:00
```yaml
---
2018-12-21 14:15:32 +00:00
# Common-Defined params
2018-11-26 19:10:09 +00:00
title: "Example article title"
date: "2017-08-21"
2018-12-21 14:15:32 +00:00
lastmod: "2018-12-21"
2018-11-26 19:10:09 +00:00
description: "Example article description"
categories:
- "Category 1"
- "Category 2"
tags:
- "Tag"
- "Another tag"
2018-11-27 20:30:08 +00:00
menu: main # Add page to a menu. Options: main, footer
2018-12-21 14:15:32 +00:00
# Theme-Defined params
comments: true # Enable/disable Disqus comments for specific post
authorbox: true # Enable/disable Authorbox for specific post
toc: true # Enable/disable Table of Contents for specific post
mathjax: true # Enable/disable MathJax for specific post
related: true # Enable/disable Related content for specific post
2018-11-26 19:10:09 +00:00
---
```
2019-01-14 13:08:53 +00:00
For more information about front matter variables and formats read [Hugo Front Matter](https://gohugo.io/content-management/front-matter) from Hugo official documentation.
### Columns
By default, **Binario** works with two columns layout (only if it possible by screen size), but you can also use one column or three columns. Change `Params.columns`to preferable value. You can also change this option for specific list pages.
### Share buttons
To display share buttons, set up `[Params.Share]` specific parameters in your site config file.
Available share buttons: Facebook, Twitter, Reddit, Telegram, LinkedIn, VK, Pocket
### Footer Social Icons
With **Binario**, you have the option to display social icons in the footer. To display them, set up `[Params.Social]` specific parameters in your site config file.
Available social services: Email, Facebook, Twitter, Telegram, Instagram, Pinterest, VK, LinkedIn, GitHub, GitLab, Stack Overflow, Mastodon, Medium
2018-11-28 15:22:51 +00:00
2018-04-25 18:30:37 +00:00
## Contributing
Have a bug? [Please open a new issue](https://github.com/vimux/binario/issues/new).
2018-04-26 18:39:01 +00:00
Pull requests are very welcome too, but please make sure they match the existing [contributing guide](https://github.com/vimux/binario/wiki/contributing).
2018-04-25 18:30:37 +00:00
## License
Binario is licensed under the [MIT License](https://github.com/vimux/binario/blob/master/LICENSE).
2018-06-18 15:33:23 +00:00
* Social media icons based on [SuperTinyIcons](https://github.com/edent/SuperTinyIcons) [MIT]
2018-11-14 14:43:53 +00:00
* CSS Reset based on [Bootstrap Reboot](https://github.com/twbs/bootstrap/blob/v4-dev/dist/css/bootstrap-reboot.css) [MIT]