From 0b84231ba689d2d0bbbe7f5f317ef2a24b6c25c5 Mon Sep 17 00:00:00 2001 From: Parsia Hakimian Date: Mon, 15 Feb 2021 03:07:56 -0800 Subject: add examplesite and modify the readme to reflect its addition (#68) --- README.md | 39 ++- exampleSite/archetypes/default.md | 6 + exampleSite/config.toml | 148 ++++++++++ exampleSite/content/page/about.md | 15 ++ exampleSite/content/post/goisforlovers.md | 343 ++++++++++++++++++++++++ exampleSite/content/post/hugoisforlovers.md | 88 ++++++ exampleSite/content/post/migrate-from-jekyll.md | 152 +++++++++++ exampleSite/content/post/shortcodes/01.jpg | Bin 0 -> 40540 bytes exampleSite/content/post/shortcodes/index.md | 110 ++++++++ sample-config.toml | 42 +-- 10 files changed, 920 insertions(+), 23 deletions(-) create mode 100644 exampleSite/archetypes/default.md create mode 100644 exampleSite/config.toml create mode 100644 exampleSite/content/page/about.md create mode 100644 exampleSite/content/post/goisforlovers.md create mode 100644 exampleSite/content/post/hugoisforlovers.md create mode 100644 exampleSite/content/post/migrate-from-jekyll.md create mode 100644 exampleSite/content/post/shortcodes/01.jpg create mode 100644 exampleSite/content/post/shortcodes/index.md diff --git a/README.md b/README.md index 5b6ddab..f4578eb 100755 --- a/README.md +++ b/README.md @@ -10,12 +10,13 @@ Live demo using the unmodified theme: [live-demo]: http://hugo-octopress-test.s3-website-us-east-1.amazonaws.com/ [test-repo]: https://github.com/parsiya/Hugo-Octopress-Test -My personal website uses the compact index (see below): +My personal website with the compact index (see below): * [https://parsiya.net](https://parsiya.net). * Source: [https://github.com/parsiya/parsiya.net](https://github.com/parsiya/parsiya.net) ## Contents +- [Quick start](#quick-start) - [Configuration](#configuration) - [Code highlight](#code-highlight) - [Blackfriday options](#blackfriday-options) @@ -53,6 +54,40 @@ My personal website uses the compact index (see below): ![screenshot](https://raw.githubusercontent.com/parsiya/Hugo-Octopress/master/images/screenshot.png) +## Quick start +Add the theme to your existing site or [Hugo's quick start][hugo-quickstart]. +All commands are run from the root directory of your website. + +[hugo-quickstart]: https://gohugo.io/getting-started/quick-start/ + +If using git to manage your website, add the theme as a git submodule: + +``` +git clone https://github.com/parsiya/Hugo-Octopress themes/Hugo-Octopress +``` + +Or you can just clone it: + +``` +git clone https://github.com/parsiya/Hugo-Octopress themes/Hugo-Octopress +``` + +To view the theme with the example site: + +``` +cd themes/Hugo-Octopress/exampleSite +hugo serve -vw +``` + +Now you can view the example website at http://localhost:1313. + +Example site created thanks to [https://github.com/nonumeros][nonumeros]. I +reviewed the [pull request][examplesite-pr] almost two years late and had to +copy/paste the website instead of resolving merge conflicts. + +[nonumeros]: https://github.com/nonumeros +[examplesite-pr]: https://github.com/parsiya/Hugo-Octopress/pull/57 + ## Configuration Hugo-Octopress can be configured by modifying the parameters in the [configuration file](https://gohugo.io/overview/configuration/). A working @@ -83,7 +118,7 @@ post = "/blog/:year-:month-:day-:title/" truncate = true # Author's name (appears in meta tags and under posts) - author = "Author's name" + author = "Author" # This text appears in site header under website title subtitle = "Subtitle appears under website title" diff --git a/exampleSite/archetypes/default.md b/exampleSite/archetypes/default.md new file mode 100644 index 0000000..00e77bd --- /dev/null +++ b/exampleSite/archetypes/default.md @@ -0,0 +1,6 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +date: {{ .Date }} +draft: true +--- + diff --git a/exampleSite/config.toml b/exampleSite/config.toml new file mode 100644 index 0000000..7d75d51 --- /dev/null +++ b/exampleSite/config.toml @@ -0,0 +1,148 @@ + +baseurl = "https://example.com" +disablePathToLower = false +languageCode = "en-us" +title = "Site title" +theme = "hugo-octopress" + +# Needed so we can serve the example website without extra switches +themesDir = "../.." + +# Disqus shortcode +# Disable comments for any individual post by adding "comments: false" in its frontmatter +# Note it's not under [params] anymore +# disqusShortname = "Your disqus shortname" + +# Number of blog posts in each pagination page +paginate = 6 + +# Code highlighting options +# Hugo uses Chroma but names are the same as the old pygments highlighter + +# 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 +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" + +[permalinks] +post = "/blog/:year-:month-:day-:title/" # change the post URL to look like the old ones + +[params] + + # --- Start sidebar options --- + # Number of last posts that will be displayed in the sidebar - set to 0 or remove to hide this section + sidebarRecentLimit = 5 + + # Sidebar header - passed to markdownify so you can write markdown here + sidebarHeader = "Sidebar Header" + + # Sidebar text also supports markdown + # New lines can be added with two spaces at the end of line. New paragraphs can be added with two an empty line. + # when adding two new lines, remember to remove the indentation otherwise the new line will be treated as a codeblock + sidebarText = """Here's a [link to example.net](https://www.example.net) + + New paragraph + + Another paragraph which has two spaces in the end to create a new line using markdown + New line but not a new paragraph + """ + # Sidebar menu - if true will add a sidebar menu between sidebar text and recent posts + sidebarMenuEnabled = true + sidebarMenuHeader = "Sidebar Links" + + # sidebar links + github = "https://github.com/parsiya/Hugo-Octopress" + bitbucket = "https://bitbucket.org/parsiya/" + twitter = "https://twitter.com/cryptogangsta/" + + # --- End sidebar options --- + + # If set to true, navigation menu links will open in a new window with the exception of links to root ("/") + # If this item does not exist or set to false, then navigation menu links will open in the same window + navigationNewWindow = true + + # If false, all of blog post will appear on front page (and in pagination) + truncate = true + + # Author's name (appears in meta tags and under posts) + author = "Author" + + # This text appears in the site header under website title + subtitle = "Subtitle appears under the website title" + + # Search engine URL + searchEngineURL = "https://www.google.com/search" + + # Text of the "Continue Reading" label. Supports markdown and inline HTML. + # For example, → == right arrow. + continueReadingText = "Would you like to know more? →" + + # Switch to true to enable RSS icon link + rss = true + + # Set to true to use a text label for RSS instead of an icon + # This is overwritten by the "rss" setting + textrss = false + + # Website's default description + description = "" + + # 404.html header and text - both support markdown + notFoundHeader = "There's nothing here" + + notFoundText = """Please either go back or use the navigation/sidebar menus. + """ + + # Set to true to hide ReadingTime on posts + disableReadingTime = false + + # Set to true to disable downloading of remote Google fonts + disableGoogleFonts = true + + # Generate taxonomy pages + generateTaxonomyList = true + +# Menu +# If navigationNewWindow (under [params]) is set to true then all links except root ("/") will open in a new window +# If it does not exist or is set to false then links will open in the same window +[[menu.main]] + Name = "Site's Home Page" + URL = "/" + weight = -5 + +[[menu.main]] + Name = "example.net" + URL = "https://www.example.net/" + weight = -5 + +[[menu.main]] + Name = "This theme on Github" + URL = "https://www.github.com/parsiya/hugo-octopress" + +[[menu.main]] + Name = "The About page" + URL = "/about" + +# Sidebar menus +# Enable with "sidebarMenuEnabled = true" under [params] +# Header text is "sidebarMenuHeader" under [params] +[[menu.sidebar]] + Name = "example.net" + URL = "https://www.example.net" + weight = 0 + +[[menu.sidebar]] + Name = "Hugo category" + URL = "/categories/golang/" + weight = 1 + +[[menu.sidebar]] + Name = "About page" + URL = "/about" + weight = 2 diff --git a/exampleSite/content/page/about.md b/exampleSite/content/page/about.md new file mode 100644 index 0000000..190f190 --- /dev/null +++ b/exampleSite/content/page/about.md @@ -0,0 +1,15 @@ +--- +title: "Single Page" +date: "2021-02-14" +url: "/about/" +--- + +This is a single page. To create a page similar to this: + +1. Create a new markdown file in `contents/page/about.md`. + 1. Alternatively, create a [page bundle][page-bundle-link] `contents/page/about/index.md`. +2. In the frontmatter of the page, set the value of `url` to your desired relative path. + 1. E.g., for this page we have `url = "/about/"`. +3. Now you can access the website at `baseurl/about` and you can link to it from the main menu or sidebar using the relative path. + +[page-bundle-link]: https://gohugo.io/content-management/page-bundles/ \ No newline at end of file diff --git a/exampleSite/content/post/goisforlovers.md b/exampleSite/content/post/goisforlovers.md new file mode 100644 index 0000000..41d20f1 --- /dev/null +++ b/exampleSite/content/post/goisforlovers.md @@ -0,0 +1,343 @@ ++++ +title = "(Hu)go Template Primer" +description = "" +tags = [ + "go", + "golang", + "templates", + "themes", + "development", +] +date = "2014-04-02" +categories = [ + "Development", + "golang", +] ++++ + +Hugo uses the excellent [go][] [html/template][gohtmltemplate] library for +its template engine. It is an extremely lightweight engine that provides a very +small amount of logic. In our experience that it is just the right amount of +logic to be able to create a good static website. If you have used other +template systems from different languages or frameworks you will find a lot of +similarities in go templates. + +This document is a brief primer on using go templates. The [go docs][gohtmltemplate] +provide more details. + +## Introduction to Go Templates + +Go templates provide an extremely simple template language. It adheres to the +belief that only the most basic of logic belongs in the template or view layer. +One consequence of this simplicity is that go templates parse very quickly. + +A unique characteristic of go templates is they are content aware. Variables and +content will be sanitized depending on the context of where they are used. More +details can be found in the [go docs][gohtmltemplate]. + +## Basic Syntax + +Go lang templates are html files with the addition of variables and +functions. + +**Go variables and functions are accessible within {{ }}** + +Accessing a predefined variable "foo": + + {{ foo }} + +**Parameters are separated using spaces** + +Calling the add function with input of 1, 2: + + {{ add 1 2 }} + +**Methods and fields are accessed via dot notation** + +Accessing the Page Parameter "bar" + + {{ .Params.bar }} + +**Parentheses can be used to group items together** + + {{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} + + +## Variables + +Each go template has a struct (object) made available to it. In hugo each +template is passed either a page or a node struct depending on which type of +page you are rendering. More details are available on the +[variables](/layout/variables) page. + +A variable is accessed by referencing the variable name. + + {{ .Title }} + +Variables can also be defined and referenced. + + {{ $address := "123 Main St."}} + {{ $address }} + + +## Functions + +Go template ship with a few functions which provide basic functionality. The go +template system also provides a mechanism for applications to extend the +available functions with their own. [Hugo template +functions](/layout/functions) provide some additional functionality we believe +are useful for building websites. Functions are called by using their name +followed by the required parameters separated by spaces. Template +functions cannot be added without recompiling hugo. + +**Example:** + + {{ add 1 2 }} + +## Includes + +When including another template you will pass to it the data it will be +able to access. To pass along the current context please remember to +include a trailing dot. The templates location will always be starting at +the /layout/ directory within Hugo. + +**Example:** + + {{ template "chrome/header.html" . }} + + +## Logic + +Go templates provide the most basic iteration and conditional logic. + +### Iteration + +Just like in go, the go templates make heavy use of range to iterate over +a map, array or slice. The following are different examples of how to use +range. + +**Example 1: Using Context** + + {{ range array }} + {{ . }} + {{ end }} + +**Example 2: Declaring value variable name** + + {{range $element := array}} + {{ $element }} + {{ end }} + +**Example 2: Declaring key and value variable name** + + {{range $index, $element := array}} + {{ $index }} + {{ $element }} + {{ end }} + +### Conditionals + +If, else, with, or, & and provide the framework for handling conditional +logic in Go Templates. Like range, each statement is closed with `end`. + + +Go Templates treat the following values as false: + +* false +* 0 +* any array, slice, map, or string of length zero + +**Example 1: If** + + {{ if isset .Params "title" }}

{{ index .Params "title" }}

{{ end }} + +**Example 2: If -> Else** + + {{ if isset .Params "alt" }} + {{ index .Params "alt" }} + {{else}} + {{ index .Params "caption" }} + {{ end }} + +**Example 3: And & Or** + + {{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} + +**Example 4: With** + +An alternative way of writing "if" and then referencing the same value +is to use "with" instead. With rebinds the context `.` within its scope, +and skips the block if the variable is absent. + +The first example above could be simplified as: + + {{ with .Params.title }}

{{ . }}

{{ end }} + +**Example 5: If -> Else If** + + {{ if isset .Params "alt" }} + {{ index .Params "alt" }} + {{ else if isset .Params "caption" }} + {{ index .Params "caption" }} + {{ end }} + +## Pipes + +One of the most powerful components of go templates is the ability to +stack actions one after another. This is done by using pipes. Borrowed +from unix pipes, the concept is simple, each pipeline's output becomes the +input of the following pipe. + +Because of the very simple syntax of go templates, the pipe is essential +to being able to chain together function calls. One limitation of the +pipes is that they only can work with a single value and that value +becomes the last parameter of the next pipeline. + +A few simple examples should help convey how to use the pipe. + +**Example 1 :** + + {{ if eq 1 1 }} Same {{ end }} + +is the same as + + {{ eq 1 1 | if }} Same {{ end }} + +It does look odd to place the if at the end, but it does provide a good +illustration of how to use the pipes. + +**Example 2 :** + + {{ index .Params "disqus_url" | html }} + +Access the page parameter called "disqus_url" and escape the HTML. + +**Example 3 :** + + {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} + Stuff Here + {{ end }} + +Could be rewritten as + + {{ isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" | if }} + Stuff Here + {{ end }} + + +## Context (aka. the dot) + +The most easily overlooked concept to understand about go templates is that {{ . }} +always refers to the current context. In the top level of your template this +will be the data set made available to it. Inside of a iteration it will have +the value of the current item. When inside of a loop the context has changed. . +will no longer refer to the data available to the entire page. If you need to +access this from within the loop you will likely want to set it to a variable +instead of depending on the context. + +**Example:** + + {{ $title := .Site.Title }} + {{ range .Params.tags }} +
  • {{ . }} - {{ $title }}
    • + {{ end }} + +Notice how once we have entered the loop the value of {{ . }} has changed. We +have defined a variable outside of the loop so we have access to it from within +the loop. + +# Hugo Parameters + +Hugo provides the option of passing values to the template language +through the site configuration (for sitewide values), or through the meta +data of each specific piece of content. You can define any values of any +type (supported by your front matter/config format) and use them however +you want to inside of your templates. + + +## Using Content (page) Parameters + +In each piece of content you can provide variables to be used by the +templates. This happens in the [front matter](/content/front-matter). + +An example of this is used in this documentation site. Most of the pages +benefit from having the table of contents provided. Sometimes the TOC just +doesn't make a lot of sense. We've defined a variable in our front matter +of some pages to turn off the TOC from being displayed. + +Here is the example front matter: + +``` +--- +title: "Permalinks" +date: "2013-11-18" +aliases: + - "/doc/permalinks/" +groups: ["extras"] +groups_weight: 30 +notoc: true +--- +``` + +Here is the corresponding code inside of the template: + + {{ if not .Params.notoc }} +
    + {{ .TableOfContents }} +
    + {{ end }} + + + +## Using Site (config) Parameters +In your top-level configuration file (eg, `config.yaml`) you can define site +parameters, which are values which will be available to you in chrome. + +For instance, you might declare: + +```yaml +params: + CopyrightHTML: "Copyright © 2013 John Doe. All Rights Reserved." + TwitterUser: "spf13" + SidebarRecentLimit: 5 +``` + +Within a footer layout, you might then declare a `