From da6509ba3c230dd7c741906db279ea35aa8ed861 Mon Sep 17 00:00:00 2001 From: vimux Date: Tue, 15 Jan 2019 10:20:19 -0500 Subject: [PATCH] Update README.md --- README.md | 128 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 97 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 929e78a..5b35fe3 100644 --- a/README.md +++ b/README.md @@ -15,19 +15,53 @@ * Related content * MathJax +## Table of Contents + +- [Installation](#installation) + - [1A. Git clone](#option-a-git-clone) + - [1B. Git submodule](#option-b-git-submodule) + - [1C. Download ZIP and manual install](#step-1b-git-submodule) +- [Configuration](#configuration) + - [Config.toml example](#configtoml-example) + - [Front Matter example](#front-matter-example) + - [Configuration options](#configuration-options) + - [Columns](#columns) + - [Post Meta](#post-meta) + - [Related Content](#related-content) + - [Share Buttons](#share-buttons) + - [Thumbnail Image](#thumbnail-image) + - [Footer Social Icons](#footer-social-icons) + - [Web App Manifest](#web-app-manifest) +- [Contributing](#contributing) +- [License](#license) + ## 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**. +*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). Also, you have git installed on your machine and you are familiar with basic git usage. After that, you ready to install **Binario**.* 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) +- **A**. [Git clone](#option-a-git-clone) +- **B**. [Git submodule](#option-b-git-submodule) +- **C**. [Download ZIP and manual install](#option-c-download-zip-and-manual-install) -*For more information read the [Install and Use Themes](https://gohugo.io/themes/installing-and-using-themes/)* +*For more information read the "[Install and Use Themes](https://gohugo.io/themes/installing-and-using-themes/)"*. -### 1A. Git submodule (Recommended) +### Option A. Git clone + +In your Hugo site directory, run: + +``` +git clone https://github.com/vimux/binario themes/binario +``` + +Next, edit your `config.toml` configuration file and add parameter: + +``` +theme = "binario" +``` + +### Option B. Git submodule In your Hugo site directory, run: @@ -43,23 +77,9 @@ 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 +### Option C. Download ZIP and manual install -In your Hugo site directory, run: - -``` -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` +**[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: @@ -69,13 +89,13 @@ theme = "binario" *** -After that, you can run your site in Hugo server mode: +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. +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. ## Configuration @@ -166,7 +186,7 @@ googleAnalytics = "" # Enable Google Analytics by entering your tracking id home = ["HTML", "RSS", "MANIFEST"] ``` -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. +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. ### Front Matter example @@ -196,24 +216,70 @@ related: true # Enable/disable Related content for specific post --- ``` -For more information about front matter variables and formats read [Hugo Front Matter](https://gohugo.io/content-management/front-matter) from Hugo official documentation. +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 +### Configuration options -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. +Binario includes some customizable configuration options that may be useful. -### Share buttons +#### Columns + +By default, Binario works with two columns layout (if it possible by screen size) for list pages, but you can also use one column or three columns layout. Change `Params.columns`to preferable value (from 1 to 3). You can also change this option for specific list pages. + +#### Post Meta + +You may activate post meta fields with `.Site.Params.post_meta` parameter. + +#### Related Content + +Binario uses default Related Content Hugo feature to provide "See Also"-like section. You can activate "Related Content" section with `.Site.Params.related` parameter. + +More information available at [Hugo Related Content](https://gohugo.io/content-management/front-matter) + +#### 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 +#### Thumbnail Image -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. +You can add thumbnail image to your content page. Just put `thumbnail.*` image file in [page bundle](https://gohugo.io/content-management/page-bundles/). + +#### 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 +#### Web App Manifest + +[Web App Manifest](https://developers.google.com/web/fundamentals/web-app-manifest/) is a simple json file with basic site info like name, description, icons, etc. This file tells the browser about your web application and how it should behave when "installed" (as PWA) on the users mobile device or desktop. + +To activate Web App Manifest you need to define `MANIFEST` custom output format & specify `[Params.Manifest]` parameters in your site config file. + +First of all, you should define `MANIFEST` custom output format [`config.toml`]: + +```toml +[outputFormats] + [outputFormats.MANIFEST] + mediaType = "application/json" + baseName = "manifest" + isPlainText = true + notAlternative = true +``` + +Then, include `MANIFEST` output format for `home` Kind attribute [`config.toml`]: + +```toml +[outputs] + home = ["HTML", "RSS", "MANIFEST"] +``` + +After that, you can specify `[Params.Manifest]` parameters. + +*To verify that your manifest file is configured properly and works well, run Hugo server and open Chrome DevTools (Press F12 in Chrome) → Application → Manifest* + ## Contributing Have a bug? [Please open a new issue](https://github.com/vimux/binario/issues/new).