From 78ec905f19f537199d82d20eb16c7132b023034e Mon Sep 17 00:00:00 2001 From: parsiya Date: Sun, 2 Sep 2018 17:46:12 -0400 Subject: Edit README --- README.md | 168 +++++++++++++++++++++++++++++++------------------------------- 1 file changed, 85 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 054e9bf..322b022 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,15 @@ # Hugo-Octopress Hugo-Octopress is a port of the classic [Octopress][octopress-link] theme to [Hugo][hugo-link]. -For a demo website using the vanilla theme please visit [http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/](http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/). +Live demo using the unmodified theme: -My personal website runs a modified version of the theme (mainly modified index): [https://parsiya.net](https://parsiya.net). +* [http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/](http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/). +* Source: [https://github.com/parsiya/Hugo-Octopress-Test](https://github.com/parsiya/Hugo-Octopress-Test). + +My personal website runs a modified version (modified index): + +* [https://parsiya.net](https://parsiya.net). +* Source: [https://github.com/parsiya/parsiya.net](https://github.com/parsiya/parsiya.net) ## Contents - [Config file parameters](#config) @@ -55,15 +61,9 @@ paginate = 6 # Configures post URLs post = "/blog/:year-:month-:day-:title/" -# Make tags and categories work -# As of Hugo v0.33 these are not needed anymore -# [indexes] -# tag = "tags" -# category = "categories" - [params] - # If false, all of blog post will appear on front page (and in pagination) + # If false, all contents of posts will appear on the front page and in pagination truncate = true # Author's name (appears in meta tags and under posts) @@ -75,8 +75,9 @@ post = "/blog/:year-:month-:day-:title/" # Search engine URL searchEngineURL = "https://www.google.com/search" - # Text of the "Continue Reading" label. → == right arrow, but it gets messed up in the string so it was added to index.html manually - continueReadingText = "Would you like to know more?" + # Text of the "Continue Reading" label. Supports markdown and inline HTML. + # For example, → == right arrow. + continueReadingText = "Would you like to know more? →" # Google analytics code - remove if you do not have/want Google Analytics - needs JavaScript googleAnalytics = "UA-XXXXX-X" @@ -96,7 +97,7 @@ post = "/blog/:year-:month-:day-:title/" # Website's default description defaultDescription = "" - # Populate this with your own search keywords - these will appear in meta tags + # Populate with your search keywords - these will appear in meta tags # defaultKeywords = ["keyword1" , "keyword2" , "keyword3" , "keyword4"] # Set to true to hide ReadingTime on posts @@ -108,43 +109,43 @@ post = "/blog/:year-:month-:day-:title/" # Remove or set to false to use local fonts remoteFonts = false - # Remove or set to false to use FontAwesome CDN, otherwise the theme uses ForkAwesome local fonts. + # Remove or set to false to use FontAwesome CDN, otherwise, the theme uses ForkAwesome local fonts. # fontAwesome = false ``` ## Code highlight -This theme use the built-in Chroma highlighter with the `solarized-dark` theme. To use the Chroma highlighter, you need to disable Pygments with `pygmentsUseClassic=false`. +This theme uses the built-in [Chroma](https://github.com/alecthomas/chroma) highlighter with the `solarized-dark` theme. See all supported styles at [https://xyproto.github.io/splash/docs/all.html](https://xyproto.github.io/splash/docs/all.html). -The following options control code highlighting: +Some options to control code highlighting: ``` toml # Highlight shortcode and code fences (```) will be treated similarly pygmentscodefences = true # Change highlight style here. -# For a full list see: https://xyproto.github.io/splash/docs/all.html +# Full list: https://xyproto.github.io/splash/docs/all.html pygmentsStyle = "solarized-dark" -# Other Chroma options can be added here (and in the highlight shortcode in the markdown file) -# See list of supported options: https://gohugo.io/content-management/syntax-highlighting/#options -# for example: pygmentsoptions = "linenos=true" +# Add other Chroma options here (override them in the highlight shortcode inside markdown) +# List of supported options: https://gohugo.io/content-management/syntax-highlighting/#options +# For example: pygmentsoptions = "linenos=true" ``` For more information see [Syntax Highlighting](https://gohugo.io/extras/highlighting/) in Hugo's documentation. ## Markdown options -Blackfriday is Hugo's markdown engine. For a list of options see [Configure Blackfriday rendering](https://gohugo.io/overview/configuration/#configure-blackfriday-rendering). Blackfriday options can be set as follows: +Blackfriday is Hugo's markdown engine. For a complete list of options see [Configure Blackfriday rendering](https://gohugo.io/getting-started/configuration/#configure-blackfriday-rendering). Blackfriday options can be set as follows: ``` toml [blackfriday] - hrefTargetBlank = true # open the external links in a new window + hrefTargetBlank = true # open external links in a new window fractions = false ``` ## CSS override -You can override the built-in CSS and use your own. Just put your own CSS files in the `static` directory of your website (the one in the theme directory also works but is not recommended for obvious reasons) and modify the `customCSS` parameter. The path should be relative to the `static` folder. These CSS files will be added through the `header` partial after the built-in CSS file. +You can override the built-in CSS and add your own. Put your CSS files in the `static` directory of your website. While storing them inside the `themes/Hugo-Octopress/static` directory works, it's not recommended (keep your website and theme as separated as possible to be able to switch themes easily). Then modify the `customCSS` parameter. The path should be relative to the `static` folder. These CSS files will be added through the `header` partial after the built-in CSS file. -For example, if your custom CSS files are `static/css/custom.css` and `static/css/custom2.css` then `customCSS` will look like this: +For example, if custom CSS files are `static/css/custom.css` and `static/css/custom2.css` then `customCSS` will look like this: ``` toml [params] @@ -152,11 +153,11 @@ For example, if your custom CSS files are `static/css/custom.css` and `static/cs ``` ## Navigation menu -Links in the navigation menu (everything other than Google search and RSS icon) can be configured here. Navigation menu is generated using the `layouts/partials/navigation.html` template. +Links in the navigation menu (everything other than Google search and RSS icon) can be customized. The navigation menu is generated using the `layouts/partials/navigation.html` partial. -By default navigation menu links will open in the same window. You can change this behavior by setting the `navigationNewWindow` parameter to true. Links to root ("/") will always open in the same window. Currently Hugo does not support adding custom attributes to menus. +By default, navigation menu links will open in the same window. You can change this behavior by setting the `navigationNewWindow` parameter to true. Links to root ("/") will always open in the same window. Currently, Hugo does not support adding custom attributes to menus. -Links are sorted according to weight from left to right. For example a link with weight of `-10` will be to the left of links with weights `0` or `10`. Links can be added to the config file like this: +Links are sorted according to weight from left to right. For example, a link with weight of `-10` will appear to the left of links with weights `0` or `10`. Links can be added to the config file: ``` toml [[menu.main]] @@ -179,7 +180,7 @@ Links are sorted according to weight from left to right. For example a link with navigationNewWindow = true ``` -Search engine can also be customized: +Search engine customization: ``` toml [params] @@ -187,22 +188,22 @@ Search engine can also be customized: ``` ## Sidebar -Sidebar has four parts. From top to bottom it has: +The sidebar has four section, from top to bottom: * Sidebar header and text (optional). -* Social network icons (optional): Icons and links to Github, Bitbucket and more. -* Sidebar menu (optional): Links in sidebar (I use them for internal category pages but you can have external links). -* Recent posts: Displays last X (default is 5) posts. +* Social network icons (optional): Icons and links to Github, Bitbucket, and more. +* Sidebar menu (optional): Links in sidebar. +* Recent posts: Displays last X posts (default is 5). -The sidebar is generated using the partial template at `layouts/partials/sidebar.html`. +The sidebar is generated using the partial at `layouts/partials/sidebar.html`. ### Sidebar text -Sidebar text has two parts and both can be configured. Both values are passed to `markdownify` so you can use markdown (e.g. add links or new lines). +The sidebar text has two parts and both can be configured. Both are passed to `markdownify` so you can use markdown (e.g. add links or new lines). -* Sidebar header appears first in an `

` tag. It can be configured through the `sidebarHeader` parameter. -* Sidebar text appears under the header and can be configured by modifying `sidebarText`. +* Sidebar header appears first in an `

` tag. It can be configured with `sidebarHeader`. +* Sidebar text appears under the header and is in `sidebarText`. -New lines can be added with `
` or in markdown format (two spaces at the end of line or one empty line in between). When adding two new lines, remember to remove the indentation at the start of the new line otherwise the it will be treated as a codeblock. +Add new lines with `
` or using markdown (two spaces at the end of a line or one empty line in between two paragraphs). When adding two spaces, remember to remove the indentation at the start of the new line otherwise the it will be treated as a codeblock. ``` toml sidebarHeader = "Sidebar Header" @@ -212,7 +213,7 @@ sidebarText = """Here's a [link to google](https://www.google.com) Second line
Third line -This line has two spaces in the end to create a new line using markdown +This line has two spaces in the end to create a new line using markdown[two spaces here] Forth line """ ``` @@ -224,22 +225,23 @@ Sidebar social network icons are configured as follows: [params] github = "https://github.com/parsiya/" bitbucket = "https://bitbucket.org/parsiya/" - gitlab = "" + gitlab = "https://gitlab.com/parsiya" twitter = "https://twitter.com/cryptogangsta/" keybase = "https://keybase.io/parsiya/" + linkedin = "https://www.linkedin.com/in/parsiya/" stackoverflow = "" - linkedin = "" googleplus = "" youtube = "" facebook = "" instagram = "" + bitcoin = "" ``` -Icon sequence can be configured in `layouts/partials/sidebar.html` (look for `
  • `). Add a `
    ` tag to create a new line. +Icon sequence is unfortunately hardcoded. To modify, copy `your-website/themes/Hugo-Octopress/layouts/partials/sidebar.html` to `your-website/layouts/partials/sidebar.html` and modify the sequence. Look for `
  • ` tags. Add a `
    ` tag to create a new line. Code to display links (and the idea to use these icons) is from [Hyde-x](https://github.com/zyro/hyde-x/). -Icons are from [http://fontawesome.io](http://fontawesome.io) by Dave Gandy. To use icons with square dark backgrounds add `-square`. For example ``. Size can be from 1 to 5 use `fa-lg` to make them adaptive. +Icons are from [Font Awesome](https://fontawesome.com/) and [Fork Awesome](https://github.com/ForkAwesome/Fork-Awesome). To use icons with square dark backgrounds add `-square`. For example ``. Size can be from 1 to 5 use `fa-lg` to make them adaptive. ### Sidebar menu This menu can be enabled by setting `sidebarMenuEnabled` to `true`. It has two parts: @@ -260,17 +262,17 @@ This menu can be enabled by setting `sidebarMenuEnabled` to `true`. It has two p ``` ### Recent posts -Last x posts can be displayed in the sidebar. This number is controlled by `sidebarRecentLimit`. To hide this section either remove `sidebarRecentLimit` from the config file or set it to zero. +Last x posts can be displayed in the sidebar. This number is controlled by `sidebarRecentLimit`. To hide this section you can remove `sidebarRecentLimit` from the config file or set it to zero. ## Shortcodes -Creating [shortcodes](https://gohugo.io/extras/shortcodes/) in Hugo was surprisingly easy (and one of the reasons I switched to it). I used two plugins in Octopress that I re-created in Hugo using shortcodes. They add captions to code blocks and images. These shortcodes are located at `layouts/shortcodes/`. +Creating [shortcodes](https://gohugo.io/extras/shortcodes/) in Hugo was surprisingly easy (and one of the reasons I switched to it). I recreated two plugins from Octopress. They add captions to code blocks and images. These shortcodes are in `layouts/shortcodes/`. -I have created a repository for all of my Hugo shortcodes at [https://github.com/parsiya/Hugo-Shortcodes](https://github.com/parsiya/Hugo-Shortcodes). +For all my Hugo shortcodes see [https://github.com/parsiya/Hugo-Shortcodes](https://github.com/parsiya/Hugo-Shortcodes). ### Code caption This shortcode adds a caption to codeblocks. The codeblock is wrapped in a `
    ` tag and caption is added using `
    `. It has two parameters, `title` which is the caption of the code block and `lang` which is the language that is passed to the Hugo's `highlight` function along with `linenos=true` to enable line numbers. -Shortcode usage (and source) is as follows (please note that parameters are named and not positional): +Usage and source (parameters are named and not positional): ``` html {{< codecaption lang="html" title="Code caption shortcode" >}} @@ -302,13 +304,13 @@ div.codewrapper { ### Image caption This shortcode adds captions to pictures. Due to the way the original CSS file was organized, this shortcode does not use `
    ` and `
    `. `Alt` tag is also set to `title`. -Usage is as follows (please note that parameters are named and not positional): +Usage (parameters are named and not positional): ``` go {{< imgcap title="Sample caption" src="/images/2016/thetheme/1.png" >}} ``` -Will result in: +Results in: ``` html @@ -318,9 +320,9 @@ Will result in: ``` ## Hugo page summary bug -Hugo will use first 70 words of the post if it does not have a summary divider. The result is usually not pretty and contains raw HTML. To avoid this, always use the summary divider `` to designate summary. +Without a summary divider ``, Hugo uses the first 70 words of the post. The result is usually not pretty and contains raw HTML. Always use the summary divider `` in your posts. -Hugo currently does not display reference style links in post summary. Because it takes everything before the summary divider and passes it to the Markdown engine (currently BlackFriday) and if your reference style links are at the bottom of the page (they usually are), they are not included. As a result your reference style links will be treated as unformatted text. You can read more about this bug [here](https://discuss.gohugo.io/t/markdown-content-renders-as-regular-text-in-summary/1396/12). +Hugo does not display render style links in the page summary if the link is also not before the summary divider. You can read more it [here](https://discuss.gohugo.io/t/markdown-content-renders-as-regular-text-in-summary/1396/12). Reference style links look like this: @@ -339,23 +341,25 @@ There are two workarounds: 2. Put the reference links before the summary divider. ## License page -License page will be located at `baseurl/license/`. Markdown code for the license page can be anywhere in the content directory, however the type of the markdown file should be set to `license` in frontmatter. For example: +License page address is `baseurl/license/`. Create a markdown file containing the text for the license page under `content` and set its type to `license` in frontmatter: - --- - title: "License" - type: license - --- +``` yaml +--- +title: "License" +type: license +--- - License text +License text +``` -License page template is located at: `layouts/license/single.html`. +License page template is: `layouts/license/single.html`. ## Table of contents -The theme supports adding `Table of Contents (ToC)` to pages. This is done in `layouts/post/single.html`. The ToC does not appear in the summary but is on top of the actual page. Currently ToC is only accessible in the templates and there is no way to access it inside the page using shortcodes. This is a limitation of BlackFriday (Hugo's markdown engine). +You can add `Table of Contents (ToC)` to pages. The ToC is on top of the actual page and does not appear in the summary. You can also use various editor plugins to manually create them inside your markdown files. -There two ways to enable the ToC: +Customize ToC either globally or for each page: -1. Each post/page can have a variable named `toc` in its frontmatter. This needs to be set to `true`. +1. Add a variable named `toc` to the frontmatter of the post/page and set it to `true`. ``` yaml title: "title" @@ -364,14 +368,14 @@ There two ways to enable the ToC: toc: true ``` -2. Global setting is available in the config file, `tableOfContents` under `[Params]` needs to be set to `true`. +2. Enable it globally by setting `tableOfContents` under `[Params]` to `true`. ``` toml [Params] tableOfContents = true ``` -The `toc` variable in frontmatter has priority. If it is set to `false` then `tableOfContents` in the config file is ignored. You skip it in the config file and set it for individual pages or enable it for all pages and disable it for specific pages in their frontmatter. +The `toc` variable in the frontmatter has priority. If it is set to `false` the global setting is ignored. ## Not Found or 404.html The `404.html` page has two optional parameters and both support markdown: @@ -379,22 +383,20 @@ The `404.html` page has two optional parameters and both support markdown: * `notFoundHeader`: 404 page title * `notFoundText`: 404 page text -If they are not set in the config file, a default page is generated. - -For extensive customization you can modify the template at `layouts/404.html` +If they are not set in the config file, theme's default page is used (`layouts/404.html`). ## Taxonomy pages -The theme can create pages that list all taxonomies (categories and tags) and their count. The taxonomy pages are at `baseURL/tags/` and `baseURL/categories`. They will be generated by `generateTaxonomyList = true`. By default items are sorted by count. `sortTaxonomyAlphabetical = true` changes the sort to alphabetical. - -For example: +You can create taxonomy lists (e.g. categories and tags). Set `generateTaxonomyList = true` to get generate them at `baseURL/tags/` and `baseURL/categories`. By default items are sorted by count. `sortTaxonomyAlphabetical = true` changes the sort to alphabetical. - [Params] - generateTaxonomyList = true +``` toml +[Params] + generateTaxonomyList = true - # Alphabetical sort - # sortTaxonomyAlphabetical = true + # Alphabetical sort + # sortTaxonomyAlphabetical = true +``` -To revert back to ByCount sort, remove `sortTaxonomyAlphabetical` or set it to false. +To revert, remove `sortTaxonomyAlphabetical` or set it to false. Note: As of Hugo 0.33, `indexes` has been removed. If your taxonomy pages are not rendered, please update to the latest version of Hugo. Templates are now at: @@ -405,18 +407,18 @@ Note: As of Hugo 0.33, `indexes` has been removed. If your taxonomy pages are no Individual pages can be created in two ways: * Create a new content file in `content/page`. -* Set the type of page to `page` in frontmatter. E.g. `type: page`. +* Create a page anywhere inside `content` and set the type `page` in frontmatter. E.g. `type: page`. -The template to individual page is at `Hugo-Octopress/layouts/page/single.html`. It can be overridden by a file in the website's `layouts/page/single.html`. +The template for individual pages is at `Hugo-Octopress/layouts/page/single.html`. It can be overridden by a file in the website's `layouts/page/single.html`. For more information see [Single Page Templates in Hugodocs](https://gohugo.io/templates/single-page-templates/). ## Disqus -Hugo supports Disqus. Note that previously Disqus short name was `[params]/disqusShortname` but it stopped working. It's most likely because my custom variable had the same name as Hugo's internal variable for Disqus. Disqus shortname is now directly in the config file (similar to baseurl for example): +Hugo supports Disqus. Note Disqus shortname is directly in the config file (and not under `params`): ``` toml disqusShortname = "whatever" ``` -The disqus partial is at `layouts/partials/disqus.html`. By default it does not add Disqus when you are testing on localhost using the test server. This can be disabled (e.g. if you want to test Disqus locally) by commenting the `if and return` lines in the partial above. +By default, Disqus is not enabled on localhost using `hugo serve`. This can be disabled (e.g. if you want to test Disqus locally) by commenting the `if and return` lines in the Disqus partial in `layouts/partials/disqus.html`. ## Twitter Card Twitter card support can be enabled in the config file under `Params`: @@ -424,7 +426,7 @@ Twitter card support can be enabled in the config file under `Params`: ``` toml [params] # Twitter card config - # Enable with this. + # Enable. twitterCardEnabled = true # Don't include the @. # twitterCardSite = @@ -433,7 +435,7 @@ Twitter card support can be enabled in the config file under `Params`: twitterCardAuthor = "CryptoGangsta" ``` -After Twitter card is enabled, you can add summary images to your posts via front matter through `twitterImage`: +After Twitter card is enabled, you can add summary images to your posts in front matter with `twitterImage`: ``` yaml twitterImage: 02-fuzzer-crash.png @@ -450,19 +452,19 @@ The template can be modified at `Hugo-Octopress/partials/custom_twitter_card.htm ## Issues/TODO If you discover any issues/bugs or want new features please use the Github issue tracker. Please keep in my mind that development has not been my day job for quite a while and I may be slow in fixing things (don't be surprised if I ask you about details). -**The css is a mess.** The CSS file is `screen.css` taken directly from the classic Octopress theme. I found it easier to just modify the templates to generate HTML code similar to Octopress' output and use the existing CSS file. It's bulky (around 53KBs and 2300 lines) and it probably has code for elements that are never used (also duplicates). It also contains the highlight code (contributes to size). +**The css is a mess.** The CSS file is taken directly from the classic Octopress theme. I found it easier to just modify the templates to generate HTML code similar to Octopress' output and use the existing CSS file. It's bulky (around 53KBs and 2300 lines) and it probably has code for elements that are never used (also duplicates). ## Attribution * [Octopress](octopress-link) is created by [Brandon Mathis](https://github.com/imathis). Octopress source can be found on [https://github.com/imathis/octopress](https://github.com/imathis/octopress). * Some code was taken from the [Hyde-x](https://github.com/zyro/hyde-x) Hugo theme by [Andrei Mihu](http://andreimihu.com/). -* Sidebar icons are from Font Awesome by Dave Gandy - http://fontawesome.io. -* Special thanks to everyone who has helped me with pull requests and issues. +* Sidebar icons are from [Font Awesome](https://github.com/FortAwesome/Font-Awesome) by Dave Gandy and [Fork Awesome](https://github.com/ForkAwesome/Fork-Awesome). +* Special thanks to everyone who has helped with pull requests and issues. ## Ported by Ported by Parsia Hakimian: -* website: [parsiya.net](https://parsiya.net) -* twitter: [@CryptoGangsta](https://twitter.com/cryptogangsta) +* Website: [parsiya.net](https://parsiya.net) +* Twitter: [@CryptoGangsta](https://twitter.com/cryptogangsta) ## Theme license Open sourced under the [MIT license](https://github.com/parsiya/Hugo-Octopress/blob/master/LICENSE.md). -- cgit v1.2.3