diff options
| author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-03-03 20:33:31 +0300 |
|---|---|---|
| committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-04-28 17:50:09 +0300 |
| commit | bd4cd112295428b7fae59231190396171c69e97c (patch) | |
| tree | 610ca6541205dd1ea59c6db306290d0a6310e400 | |
| parent | cde91480c8466c3049f98ad84805c3f60ce9ea0c (diff) | |
New content structure outline
Updates #1
178 files changed, 21494 insertions, 291 deletions
@@ -2,4 +2,5 @@ node_modules/ public/ resources/ hugo_stats.json -.vscode/
\ No newline at end of file +.vscode/ +.DS_Store
\ No newline at end of file diff --git a/assets/css/components/all.css b/assets/css/components/all.css index f94f7e4..6ba0563 100644 --- a/assets/css/components/all.css +++ b/assets/css/components/all.css @@ -1,4 +1,5 @@ @import "variables.css"; +@import "fonts.css"; @import "chroma.css"; @import "chroma_dark.css"; @import "code.css"; diff --git a/assets/css/components/code.css b/assets/css/components/code.css index 404f2cb..cd6e74d 100644 --- a/assets/css/components/code.css +++ b/assets/css/components/code.css @@ -1,5 +1,5 @@ .highlight { - background-color: #f3f4f4; + @apply bg-gray-50; } .dark .highlight { @@ -115,4 +115,4 @@ pre { .goat { background-color: #f3f4f4; overflow: hidden; -}
\ No newline at end of file +} diff --git a/assets/css/components/fonts.css b/assets/css/components/fonts.css new file mode 100644 index 0000000..f116aff --- /dev/null +++ b/assets/css/components/fonts.css @@ -0,0 +1,45 @@ +/* mulish-200 - latin */ +@font-face { + font-family: 'Mulish'; + font-style: normal; + font-weight: 200; + src: local(''), + url('../fonts/mulish-v10-latin-200.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ + url('../fonts/mulish-v10-latin-200.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ + } + /* mulish-regular - latin */ + @font-face { + font-family: 'Mulish'; + font-style: normal; + font-weight: 400; + src: local(''), + url('../fonts/mulish-v10-latin-regular.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ + url('../fonts/mulish-v10-latin-regular.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ + } + /* mulish-800 - latin */ + @font-face { + font-family: 'Mulish'; + font-style: normal; + font-weight: 800; + src: local(''), + url('../fonts/mulish-v10-latin-800.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ + url('../fonts/mulish-v10-latin-800.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ + } + /* mulish-italic - latin */ + @font-face { + font-family: 'Mulish'; + font-style: italic; + font-weight: 400; + src: local(''), + url('../fonts/mulish-v10-latin-italic.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ + url('../fonts/mulish-v10-latin-italic.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ + } + /* mulish-800italic - latin */ + @font-face { + font-family: 'Mulish'; + font-style: italic; + font-weight: 800; + src: local(''), + url('../fonts/mulish-v10-latin-800italic.woff2') format('woff2'), /* Chrome 26+, Opera 23+, Firefox 39+ */ + url('../fonts/mulish-v10-latin-800italic.woff') format('woff'); /* Chrome 6+, Firefox 3.6+, IE 9+, Safari 5.1+ */ + }
\ No newline at end of file diff --git a/assets/css/sections/all.css b/assets/css/sections/all.css new file mode 100644 index 0000000..7fae6d3 --- /dev/null +++ b/assets/css/sections/all.css @@ -0,0 +1 @@ +@import "documentation.css"; diff --git a/assets/css/sections/documentation.css b/assets/css/sections/documentation.css new file mode 100644 index 0000000..ab8c701 --- /dev/null +++ b/assets/css/sections/documentation.css @@ -0,0 +1,13 @@ + + +.documentation .funcsig { + @apply tracking-tighter font-mono text-gray-600 border border-gray-200 -mt-1 p-2 w-3/4; + +} + + +.documentation .funcsig a{ + @apply text-blue-700 hover:text-steel-500 no-underline; +} + + diff --git a/assets/css/styles.css b/assets/css/styles.css index cbf6ca6..53c3a59 100644 --- a/assets/css/styles.css +++ b/assets/css/styles.css @@ -3,40 +3,35 @@ @tailwind utilities; @import "components/all.css"; +@import "sections/all.css"; html { - font-size: 14px; -} - -@screen md { - html { - font-size: 16px; - } + font-size: 14px; } body { - -moz-osx-font-smoothing: grayscale; - -webkit-font-smoothing: antialiased; - fill: currentColor; /* Applies to SVG only */ + -moz-osx-font-smoothing: grayscale; + -webkit-font-smoothing: antialiased; + fill: currentColor; /* Applies to SVG only */ } .nested-blockquote blockquote { - border-left: 4px solid var(--primary-color); - padding-left: 1em; - /*margin: 0;*/ + border-left: 4px solid var(--primary-color); + padding-left: 1em; + /*margin: 0;*/ } .mw-90 { - max-width: 90%; + max-width: 90%; } -/* Combine with classes in skins and skins-pseudo for +/* Combine with classes in skins and skins-pseudo for * many different transition possibilities. */ .bg-animate, .bg-animate:hover, .bg-animate:focus { - -webkit-transition: background-color 0.15s ease-in-out; - transition: background-color 0.15s ease-in-out; + -webkit-transition: background-color 0.15s ease-in-out; + transition: background-color 0.15s ease-in-out; } /* @@ -45,36 +40,36 @@ body { */ .dim { - opacity: 1; - -webkit-transition: opacity 0.15s ease-in; - transition: opacity 0.15s ease-in; + opacity: 1; + -webkit-transition: opacity 0.15s ease-in; + transition: opacity 0.15s ease-in; } .dim:hover, .dim:focus { - opacity: 0.5; - -webkit-transition: opacity 0.15s ease-in; - transition: opacity 0.15s ease-in; + opacity: 0.5; + -webkit-transition: opacity 0.15s ease-in; + transition: opacity 0.15s ease-in; } .dim:active { - opacity: 0.8; - -webkit-transition: opacity 0.15s ease-out; - transition: opacity 0.15s ease-out; + opacity: 0.8; + -webkit-transition: opacity 0.15s ease-out; + transition: opacity 0.15s ease-out; } @layer components { - .btn-primary { - @apply py-2 px-4 font-semibold rounded-md shadow-md bg-steel-600 hover:bg-steel-700 text-white hover:text-gray-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-steel-500; - } + .btn-primary { + @apply py-2 px-4 font-semibold rounded-md shadow-md bg-steel-600 hover:bg-steel-700 text-white hover:text-gray-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-steel-500; + } - .btn-secondary { - @apply py-2 px-4 font-semibold rounded-md shadow-md bg-green-600 hover:bg-green-700 text-white hover:text-gray-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-steel-500; - } + .btn-secondary { + @apply py-2 px-4 font-semibold rounded-md shadow-md bg-green-600 hover:bg-green-700 text-white hover:text-gray-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-steel-500; + } - a { - @apply text-blue-700 hover:text-steel-500 no-underline; - } + a { + @apply text-blue-700 hover:text-steel-500 no-underline; + } - .dark a { - @apply text-steel-600 hover:text-steel-400 no-underline; - } + .dark a { + @apply text-steel-600 hover:text-steel-400 no-underline; + } } diff --git a/assets/js/main/index.js b/assets/js/main/index.js index 476bcd3..e902c65 100644 --- a/assets/js/main/index.js +++ b/assets/js/main/index.js @@ -1,5 +1,5 @@ import * as params from "@params"; -import { newNavStore, initColorScheme, bridgeTurboAndAlpine } from "./nav/index"; +import { newNavStore, newDocTreeController, initColorScheme, bridgeTurboAndAlpine } from "./nav/index"; import Alpine from "jslibs/alpinejs/v3/alpinejs/dist/module.esm.js"; import intersect from "jslibs/alpinejs/v3/intersect/dist/module.esm.js"; import persist from "jslibs/alpinejs/v3/persist/dist/module.esm.js"; @@ -39,6 +39,7 @@ import focus from "jslibs/alpinejs/v3/focus/dist/module.esm.js"; api_key: "167e7998590aebda7f9fedcf86bc4a55", }; + Alpine.data("docTreeController", () => newDocTreeController()); Alpine.data("searchController", () => newSearchController(searchConfig)); } @@ -55,6 +56,24 @@ import focus from "jslibs/alpinejs/v3/focus/dist/module.esm.js"; // Start the Turbo-Alpine bridge. bridgeTurboAndAlpine(Alpine); + + let containerScrollTops = {}; + + // To preserve scroll position in scrolling elements on navigation add data-turbo-preserve-scroll-container="somename" to the scrolling container. + addEventListener("turbo:click", () => { + document.querySelectorAll("[data-turbo-preserve-scroll-container]").forEach((ele) => { + containerScrollTops[ele.dataset.turboPreserveScrollContainer] = ele.scrollTop; + }); + }); + + addEventListener("turbo:load", () => { + document.querySelectorAll("[data-turbo-preserve-scroll-container]").forEach((ele) => { + const containerScrollTop = containerScrollTops[ele.dataset.turboPreserveScrollContainer]; + if (containerScrollTop) ele.scrollTo(0, containerScrollTop); + }); + + containerScrollTops = {}; + }); })(); // TODO(bep) move out into its own file, also pull params out into config. diff --git a/assets/js/main/nav/alpine-turbo-bridge.js b/assets/js/main/nav/alpine-turbo-bridge.js index 047e8f5..164a43f 100644 --- a/assets/js/main/nav/alpine-turbo-bridge.js +++ b/assets/js/main/nav/alpine-turbo-bridge.js @@ -1,28 +1,28 @@ export function bridgeTurboAndAlpine(Alpine) { - document.addEventListener('turbo:render', () => { - if (document.documentElement.hasAttribute('data-turbo-preview')) { - return; - } + document.addEventListener("turbo:render", () => { + if (document.documentElement.hasAttribute("data-turbo-preview")) { + return; + } - // Restart Alpine. - Alpine.start(); - }); + // Restart Alpine. + Alpine.start(); + }); - // Cleanup Alpine state on navigation. - document.addEventListener('turbo:before-cache', () => { - Alpine.stopObservingMutations(); + // Cleanup Alpine state on navigation. + document.addEventListener("turbo:before-cache", () => { + Alpine.stopObservingMutations(); - document.body.querySelectorAll('[x-data]').forEach((el) => { - if (el.hasAttribute('data-turbo-permanent')) { - el._x_ignore = true; - } else { - Alpine.destroyTree(el); + document.body.querySelectorAll("[x-data]").forEach((el) => { + if (el.hasAttribute("data-turbo-permanent")) { + el._x_ignore = true; + } else { + Alpine.destroyTree(el); - // Turbo leaks DOM elements via their data-turbo-permanent handling. - // That needs to be fixed upstream, but until then. - let clone = el.cloneNode(true); - el.replaceWith(clone); - } - }); - }); + // Turbo leaks DOM elements via their data-turbo-permanent handling. + // That needs to be fixed upstream, but until then. + let clone = el.cloneNode(true); + el.replaceWith(clone); + } + }); + }); } diff --git a/assets/js/main/nav/doctree.js b/assets/js/main/nav/doctree.js new file mode 100644 index 0000000..80b2c24 --- /dev/null +++ b/assets/js/main/nav/doctree.js @@ -0,0 +1,64 @@ +export function newDocTreeController() { + var debug = 1 ? console.log.bind(console, "[doctree]") : function () {}; + + return { + treeState: { + // The href of the current page. + currentNode: "", + }, + init: async function () { + // Holds all the documentation sections. + let docTree = await (await fetch("/doctree.json")).json(); + const setTreeState = (node) => { + this.treeState[node.href] = { + open: false, + }; + if (!node.children) return; + node.children.forEach((element) => { + // Recurse down the tree. + setTreeState(element); + }); + }; + + setTreeState(docTree); + this.setCurrentActive(); + }, + + setCurrentActive: function () { + let ref = location.pathname; + this.treeState.currentNode = ref; + for (let key in this.treeState) { + if (ref == key || ref.startsWith(key)) { + this.treeState[key].open = true; + } + } + }, + + isCurrent: function (ref) { + return this.treeState.currentNode == ref; + }, + + onBeforeRender: function () { + debug("onBeforeRender"); + this.setCurrentActive(); + }, + + toggleNode: function (ref) { + let node = this.treeState[ref]; + if (!node) { + return; + } + let wasOpen = node.open; + node.open = !node.open; + if (!wasOpen) { + Turbo.visit(ref); + } + }, + + isOpen: function (ref) { + let node = this.treeState[ref]; + if (!node) return false; + return node.open; + }, + }; +} diff --git a/assets/js/main/nav/index.js b/assets/js/main/nav/index.js index dde376f..ee43053 100644 --- a/assets/js/main/nav/index.js +++ b/assets/js/main/nav/index.js @@ -1,2 +1,3 @@ export * from "./alpine-turbo-bridge"; +export * from "./doctree"; export * from "./nav-store"; diff --git a/config.toml b/config.toml index dce27a0..c3bce85 100644 --- a/config.toml +++ b/config.toml @@ -2,6 +2,7 @@ baseURL = "https://example.org" disableKinds = ["page", "section", "taxonomy", "term"] + [module] [module.hugoVersion] extended = false diff --git a/data/docs.json b/data/docs.json new file mode 100644 index 0000000..944311d --- /dev/null +++ b/data/docs.json @@ -0,0 +1,5696 @@ +{ + "chroma": { + "lexers": [ + { + "Name": "ABAP", + "Aliases": [ + "ABAP", + "abap" + ] + }, + { + "Name": "ABNF", + "Aliases": [ + "abnf" + ] + }, + { + "Name": "ActionScript", + "Aliases": [ + "actionscript", + "as" + ] + }, + { + "Name": "ActionScript 3", + "Aliases": [ + "actionscript3", + "as", + "as3" + ] + }, + { + "Name": "Ada", + "Aliases": [ + "ada", + "ada2005", + "ada95", + "adb", + "ads" + ] + }, + { + "Name": "AL", + "Aliases": [ + "al", + "dal" + ] + }, + { + "Name": "Angular2", + "Aliases": [ + "ng2" + ] + }, + { + "Name": "ANTLR", + "Aliases": [ + "antlr" + ] + }, + { + "Name": "ApacheConf", + "Aliases": [ + "aconf", + "apache", + "apacheconf", + "conf", + "htaccess" + ] + }, + { + "Name": "APL", + "Aliases": [ + "apl" + ] + }, + { + "Name": "AppleScript", + "Aliases": [ + "applescript" + ] + }, + { + "Name": "Arduino", + "Aliases": [ + "arduino", + "ino" + ] + }, + { + "Name": "ArmAsm", + "Aliases": [ + "S", + "armasm", + "s" + ] + }, + { + "Name": "Awk", + "Aliases": [ + "awk", + "gawk", + "mawk", + "nawk" + ] + }, + { + "Name": "Ballerina", + "Aliases": [ + "bal", + "ballerina" + ] + }, + { + "Name": "Base Makefile", + "Aliases": [ + "*", + "bsdmake", + "mak", + "make", + "makefile", + "mf", + "mk" + ] + }, + { + "Name": "Bash", + "Aliases": [ + "bash", + "bash_*", + "bashrc", + "ebuild", + "eclass", + "env", + "exheres-0", + "exlib", + "ksh", + "sh", + "shell", + "zsh", + "zshrc" + ] + }, + { + "Name": "BashSession", + "Aliases": [ + "bash-session", + "console", + "sh-session", + "shell-session" + ] + }, + { + "Name": "Batchfile", + "Aliases": [ + "bat", + "batch", + "cmd", + "dosbatch", + "winbatch" + ] + }, + { + "Name": "BibTeX", + "Aliases": [ + "bib", + "bibtex" + ] + }, + { + "Name": "Bicep", + "Aliases": [ + "bicep" + ] + }, + { + "Name": "BlitzBasic", + "Aliases": [ + "b3d", + "bb", + "blitzbasic", + "bplus", + "decls" + ] + }, + { + "Name": "BNF", + "Aliases": [ + "bnf" + ] + }, + { + "Name": "Brainfuck", + "Aliases": [ + "b", + "bf", + "brainfuck" + ] + }, + { + "Name": "C", + "Aliases": [ + "c", + "h", + "idc", + "x[bp]m" + ] + }, + { + "Name": "C#", + "Aliases": [ + "c#", + "cs", + "csharp" + ] + }, + { + "Name": "C++", + "Aliases": [ + "C", + "CPP", + "H", + "c++", + "cc", + "cp", + "cpp", + "cxx", + "h++", + "hh", + "hpp", + "hxx" + ] + }, + { + "Name": "Caddyfile", + "Aliases": [ + "caddy", + "caddyfile" + ] + }, + { + "Name": "Caddyfile Directives", + "Aliases": [ + "caddy-d", + "caddyfile-d", + "caddyfile-directives" + ] + }, + { + "Name": "Cap'n Proto", + "Aliases": [ + "capnp" + ] + }, + { + "Name": "Cassandra CQL", + "Aliases": [ + "cassandra", + "cql" + ] + }, + { + "Name": "Ceylon", + "Aliases": [ + "ceylon" + ] + }, + { + "Name": "CFEngine3", + "Aliases": [ + "cf", + "cf3", + "cfengine3" + ] + }, + { + "Name": "cfstatement", + "Aliases": [ + "cfs" + ] + }, + { + "Name": "ChaiScript", + "Aliases": [ + "chai", + "chaiscript" + ] + }, + { + "Name": "Cheetah", + "Aliases": [ + "cheetah", + "spitfire", + "spt", + "tmpl" + ] + }, + { + "Name": "Clojure", + "Aliases": [ + "clj", + "clojure" + ] + }, + { + "Name": "CMake", + "Aliases": [ + "cmake", + "txt" + ] + }, + { + "Name": "COBOL", + "Aliases": [ + "COB", + "CPY", + "cob", + "cobol", + "cpy" + ] + }, + { + "Name": "CoffeeScript", + "Aliases": [ + "coffee", + "coffee-script", + "coffeescript" + ] + }, + { + "Name": "Common Lisp", + "Aliases": [ + "cl", + "common-lisp", + "lisp" + ] + }, + { + "Name": "Coq", + "Aliases": [ + "coq", + "v" + ] + }, + { + "Name": "Crystal", + "Aliases": [ + "cr", + "crystal" + ] + }, + { + "Name": "CSS", + "Aliases": [ + "css" + ] + }, + { + "Name": "Cython", + "Aliases": [ + "cython", + "pxd", + "pxi", + "pyrex", + "pyx" + ] + }, + { + "Name": "D", + "Aliases": [ + "d", + "di" + ] + }, + { + "Name": "Dart", + "Aliases": [ + "dart" + ] + }, + { + "Name": "Diff", + "Aliases": [ + "diff", + "patch", + "udiff" + ] + }, + { + "Name": "Django/Jinja", + "Aliases": [ + "django", + "jinja" + ] + }, + { + "Name": "Docker", + "Aliases": [ + "docker", + "dockerfile" + ] + }, + { + "Name": "DTD", + "Aliases": [ + "dtd" + ] + }, + { + "Name": "Dylan", + "Aliases": [ + "dyl", + "dylan", + "intr" + ] + }, + { + "Name": "EBNF", + "Aliases": [ + "ebnf" + ] + }, + { + "Name": "Elixir", + "Aliases": [ + "elixir", + "ex", + "exs" + ] + }, + { + "Name": "Elm", + "Aliases": [ + "elm" + ] + }, + { + "Name": "EmacsLisp", + "Aliases": [ + "el", + "elisp", + "emacs", + "emacs-lisp" + ] + }, + { + "Name": "Erlang", + "Aliases": [ + "erl", + "erlang", + "es", + "escript", + "hrl" + ] + }, + { + "Name": "Factor", + "Aliases": [ + "factor" + ] + }, + { + "Name": "Fennel", + "Aliases": [ + "fennel", + "fnl" + ] + }, + { + "Name": "Fish", + "Aliases": [ + "fish", + "fishshell", + "load" + ] + }, + { + "Name": "Forth", + "Aliases": [ + "forth", + "frt", + "fs", + "fth" + ] + }, + { + "Name": "Fortran", + "Aliases": [ + "F03", + "F90", + "f03", + "f90", + "fortran" + ] + }, + { + "Name": "FortranFixed", + "Aliases": [ + "F", + "f", + "fortranfixed" + ] + }, + { + "Name": "FSharp", + "Aliases": [ + "fs", + "fsharp", + "fsi" + ] + }, + { + "Name": "GAS", + "Aliases": [ + "S", + "asm", + "gas", + "s" + ] + }, + { + "Name": "GDScript", + "Aliases": [ + "gd", + "gdscript" + ] + }, + { + "Name": "Genshi", + "Aliases": [ + "genshi", + "kid", + "xml+genshi", + "xml+kid" + ] + }, + { + "Name": "Genshi HTML", + "Aliases": [ + "html+genshi", + "html+kid" + ] + }, + { + "Name": "Genshi Text", + "Aliases": [ + "genshitext" + ] + }, + { + "Name": "Gherkin", + "Aliases": [ + "Cucumber", + "FEATURE", + "Gherkin", + "cucumber", + "feature", + "gherkin" + ] + }, + { + "Name": "GLSL", + "Aliases": [ + "frag", + "geo", + "glsl", + "vert" + ] + }, + { + "Name": "Gnuplot", + "Aliases": [ + "gnuplot", + "plot", + "plt" + ] + }, + { + "Name": "Go", + "Aliases": [ + "go", + "golang" + ] + }, + { + "Name": "Go HTML Template", + "Aliases": [ + "go-html-template" + ] + }, + { + "Name": "Go Text Template", + "Aliases": [ + "go-text-template" + ] + }, + { + "Name": "GraphQL", + "Aliases": [ + "gql", + "graphql", + "graphqls" + ] + }, + { + "Name": "Groff", + "Aliases": [ + "1p", + "3pm", + "[1-9]", + "groff", + "man", + "nroff" + ] + }, + { + "Name": "Groovy", + "Aliases": [ + "gradle", + "groovy" + ] + }, + { + "Name": "Handlebars", + "Aliases": [ + "handlebars", + "hbs" + ] + }, + { + "Name": "Haskell", + "Aliases": [ + "haskell", + "hs" + ] + }, + { + "Name": "Haxe", + "Aliases": [ + "haxe", + "hx", + "hxsl" + ] + }, + { + "Name": "HCL", + "Aliases": [ + "hcl" + ] + }, + { + "Name": "Hexdump", + "Aliases": [ + "hexdump" + ] + }, + { + "Name": "HLB", + "Aliases": [ + "hlb" + ] + }, + { + "Name": "HTML", + "Aliases": [ + "htm", + "html", + "xhtml", + "xslt" + ] + }, + { + "Name": "HTTP", + "Aliases": [ + "http" + ] + }, + { + "Name": "Hy", + "Aliases": [ + "hy", + "hylang" + ] + }, + { + "Name": "Idris", + "Aliases": [ + "idr", + "idris" + ] + }, + { + "Name": "Igor", + "Aliases": [ + "igor", + "igorpro", + "ipf" + ] + }, + { + "Name": "INI", + "Aliases": [ + "cfg", + "dosini", + "editorconfig", + "gitconfig", + "inf", + "ini" + ] + }, + { + "Name": "Io", + "Aliases": [ + "io" + ] + }, + { + "Name": "J", + "Aliases": [ + "ijs", + "j" + ] + }, + { + "Name": "Java", + "Aliases": [ + "java" + ] + }, + { + "Name": "JavaScript", + "Aliases": [ + "javascript", + "js", + "jsm", + "mjs" + ] + }, + { + "Name": "JSON", + "Aliases": [ + "json" + ] + }, + { + "Name": "Julia", + "Aliases": [ + "jl", + "julia" + ] + }, + { + "Name": "Jungle", + "Aliases": [ + "jungle" + ] + }, + { + "Name": "Kotlin", + "Aliases": [ + "kotlin", + "kt" + ] + }, + { + "Name": "Lighttpd configuration file", + "Aliases": [ + "lighttpd", + "lighty" + ] + }, + { + "Name": "LLVM", + "Aliases": [ + "ll", + "llvm" + ] + }, + { + "Name": "Lua", + "Aliases": [ + "lua", + "wlua" + ] + }, + { + "Name": "Mako", + "Aliases": [ + "mako", + "mao" + ] + }, + { + "Name": "markdown", + "Aliases": [ + "markdown", + "md", + "mkd" + ] + }, + { + "Name": "Mason", + "Aliases": [ + "m", + "mason", + "mc", + "mhtml", + "mi" + ] + }, + { + "Name": "Mathematica", + "Aliases": [ + "cdf", + "ma", + "mathematica", + "mma", + "nb", + "nbp" + ] + }, + { + "Name": "Matlab", + "Aliases": [ + "m", + "matlab" + ] + }, + { + "Name": "mcfunction", + "Aliases": [ + "mcfunction" + ] + }, + { + "Name": "Meson", + "Aliases": [ + "build", + "meson", + "meson.build", + "txt" + ] + }, + { + "Name": "Metal", + "Aliases": [ + "metal" + ] + }, + { + "Name": "MiniZinc", + "Aliases": [ + "MZN", + "dzn", + "fzn", + "minizinc", + "mzn" + ] + }, + { + "Name": "MLIR", + "Aliases": [ + "mlir" + ] + }, + { + "Name": "Modula-2", + "Aliases": [ + "def", + "m2", + "mod", + "modula2" + ] + }, + { + "Name": "MonkeyC", + "Aliases": [ + "mc", + "monkeyc" + ] + }, + { + "Name": "MorrowindScript", + "Aliases": [ + "morrowind", + "mwscript" + ] + }, + { + "Name": "Myghty", + "Aliases": [ + "myghty", + "myt" + ] + }, + { + "Name": "MySQL", + "Aliases": [ + "mysql", + "sql" + ] + }, + { + "Name": "NASM", + "Aliases": [ + "ASM", + "asm", + "nasm" + ] + }, + { + "Name": "Newspeak", + "Aliases": [ + "newspeak", + "ns2" + ] + }, + { + "Name": "Nginx configuration file", + "Aliases": [ + "conf", + "nginx" + ] + }, + { + "Name": "Nim", + "Aliases": [ + "nim", + "nimrod" + ] + }, + { + "Name": "Nix", + "Aliases": [ + "nix", + "nixos" + ] + }, + { + "Name": "Objective-C", + "Aliases": [ + "h", + "m", + "obj-c", + "objc", + "objective-c", + "objectivec" + ] + }, + { + "Name": "OCaml", + "Aliases": [ + "ml", + "mli", + "mll", + "mly", + "ocaml" + ] + }, + { + "Name": "Octave", + "Aliases": [ + "m", + "octave" + ] + }, + { + "Name": "OnesEnterprise", + "Aliases": [ + "1S", + "1S:Enterprise", + "EPF", + "ERF", + "epf", + "erf", + "ones", + "onesenterprise" + ] + }, + { + "Name": "OpenEdge ABL", + "Aliases": [ + "abl", + "cls", + "i", + "openedge", + "openedgeabl", + "p", + "progress", + "w" + ] + }, + { + "Name": "OpenSCAD", + "Aliases": [ + "openscad", + "scad" + ] + }, + { + "Name": "Org Mode", + "Aliases": [ + "org", + "orgmode" + ] + }, + { + "Name": "PacmanConf", + "Aliases": [ + "conf", + "pacmanconf" + ] + }, + { + "Name": "Perl", + "Aliases": [ + "perl", + "pl", + "pm", + "t" + ] + }, + { + "Name": "PHP", + "Aliases": [ + "inc", + "php", + "php3", + "php4", + "php5", + "php[345]" + ] + }, + { + "Name": "PHTML", + "Aliases": [ + "inc", + "php", + "php[345]", + "phtml" + ] + }, + { + "Name": "Pig", + "Aliases": [ + "pig" + ] + }, + { + "Name": "PkgConfig", + "Aliases": [ + "pc", + "pkgconfig" + ] + }, + { + "Name": "PL/pgSQL", + "Aliases": [ + "plpgsql" + ] + }, + { + "Name": "plaintext", + "Aliases": [ + "no-highlight", + "plain", + "text", + "txt" + ] + }, + { + "Name": "Plutus Core", + "Aliases": [ + "plc", + "plutus-core" + ] + }, + { + "Name": "Pony", + "Aliases": [ + "pony" + ] + }, + { + "Name": "PostgreSQL SQL dialect", + "Aliases": [ + "postgres", + "postgresql" + ] + }, + { + "Name": "PostScript", + "Aliases": [ + "eps", + "postscr", + "postscript", + "ps" + ] + }, + { + "Name": "POVRay", + "Aliases": [ + "inc", + "pov" + ] + }, + { + "Name": "PowerQuery", + "Aliases": [ + "powerquery", + "pq" + ] + }, + { + "Name": "PowerShell", + "Aliases": [ + "posh", + "powershell", + "ps1", + "psd1", + "psm1" + ] + }, + { + "Name": "Prolog", + "Aliases": [ + "ecl", + "pl", + "pro", + "prolog" + ] + }, + { + "Name": "PromQL", + "Aliases": [ + "promql" + ] + }, + { + "Name": "Protocol Buffer", + "Aliases": [ + "proto", + "protobuf" + ] + }, + { + "Name": "Puppet", + "Aliases": [ + "pp", + "puppet" + ] + }, + { + "Name": "Python", + "Aliases": [ + "bazel", + "bzl", + "jy", + "py", + "py3", + "pyi", + "python", + "python3", + "pyw", + "sage", + "sc", + "tac" + ] + }, + { + "Name": "Python 2", + "Aliases": [ + "py2", + "python2" + ] + }, + { + "Name": "QBasic", + "Aliases": [ + "BAS", + "bas", + "basic", + "qbasic" + ] + }, + { + "Name": "QML", + "Aliases": [ + "qbs", + "qml" + ] + }, + { + "Name": "R", + "Aliases": [ + "R", + "Renviron", + "Rhistory", + "Rprofile", + "S", + "r", + "s", + "splus" + ] + }, + { + "Name": "Racket", + "Aliases": [ + "racket", + "rkt", + "rktd", + "rktl" + ] + }, + { + "Name": "Ragel", + "Aliases": [ + "ragel" + ] + }, + { + "Name": "Raku", + "Aliases": [ + "6pl", + "6pm", + "nqp", + "p6", + "p6l", + "p6m", + "perl6", + "pl", + "pl6", + "pm", + "pm6", + "raku", + "rakudoc", + "rakumod", + "rakutest", + "t" + ] + }, + { + "Name": "react", + "Aliases": [ + "jsx", + "react" + ] + }, + { + "Name": "ReasonML", + "Aliases": [ + "re", + "reason", + "reasonml", + "rei" + ] + }, + { + "Name": "reg", + "Aliases": [ + "reg", + "registry" + ] + }, + { + "Name": "reStructuredText", + "Aliases": [ + "rest", + "restructuredtext", + "rst" + ] + }, + { + "Name": "Rexx", + "Aliases": [ + "arexx", + "rex", + "rexx", + "rx" + ] + }, + { + "Name": "Ruby", + "Aliases": [ + "duby", + "gemspec", + "rake", + "rb", + "rbw", + "rbx", + "ruby" + ] + }, + { + "Name": "Rust", + "Aliases": [ + "in", + "rs", + "rust" + ] + }, + { + "Name": "SAS", + "Aliases": [ + "SAS", + "sas" + ] + }, + { + "Name": "Sass", + "Aliases": [ + "sass" + ] + }, + { + "Name": "Scala", + "Aliases": [ + "scala" + ] + }, + { + "Name": "Scheme", + "Aliases": [ + "scheme", + "scm", + "ss" + ] + }, + { + "Name": "Scilab", + "Aliases": [ + "sce", + "sci", + "scilab", + "tst" + ] + }, + { + "Name": "SCSS", + "Aliases": [ + "scss" + ] + }, + { + "Name": "Sieve", + "Aliases": [ + "sieve", + "siv" + ] + }, + { + "Name": "Smalltalk", + "Aliases": [ + "smalltalk", + "squeak", + "st" + ] + }, + { + "Name": "Smarty", + "Aliases": [ + "smarty", + "tpl" + ] + }, + { + "Name": "Snobol", + "Aliases": [ + "snobol" + ] + }, + { + "Name": "Solidity", + "Aliases": [ + "sol", + "solidity" + ] + }, + { + "Name": "SPARQL", + "Aliases": [ + "rq", + "sparql" + ] + }, + { + "Name": "SQL", + "Aliases": [ + "sql" + ] + }, + { + "Name": "SquidConf", + "Aliases": [ + "conf", + "squid", + "squid.conf", + "squidconf" + ] + }, + { + "Name": "Standard ML", + "Aliases": [ + "fun", + "sig", + "sml" + ] + }, + { + "Name": "Stylus", + "Aliases": [ + "styl", + "stylus" + ] + }, + { + "Name": "Svelte", + "Aliases": [ + "svelte" + ] + }, + { + "Name": "Swift", + "Aliases": [ + "swift" + ] + }, + { + "Name": "SYSTEMD", + "Aliases": [ + "automount", + "device", + "dnssd", + "link", + "mount", + "netdev", + "network", + "path", + "scope", + "service", + "slice", + "socket", + "swap", + "systemd", + "target", + "timer" + ] + }, + { + "Name": "systemverilog", + "Aliases": [ + "sv", + "svh", + "systemverilog" + ] + }, + { + "Name": "TableGen", + "Aliases": [ + "tablegen", + "td" + ] + }, + { + "Name": "TASM", + "Aliases": [ + "ASM", + "asm", + "tasm" + ] + }, + { + "Name": "Tcl", + "Aliases": [ + "rvt", + "tcl" + ] + }, + { + "Name": "Tcsh", + "Aliases": [ + "csh", + "tcsh" + ] + }, + { + "Name": "Termcap", + "Aliases": [ + "src", + "termcap" + ] + }, + { + "Name": "Terminfo", + "Aliases": [ + "src", + "terminfo" + ] + }, + { + "Name": "Terraform", + "Aliases": [ + "terraform", + "tf" + ] + }, + { + "Name": "TeX", + "Aliases": [ + "aux", + "latex", + "tex", + "toc" + ] + }, + { + "Name": "Thrift", + "Aliases": [ + "thrift" + ] + }, + { + "Name": "TOML", + "Aliases": [ + "toml" + ] + }, + { + "Name": "TradingView", + "Aliases": [ + "tradingview", + "tv" + ] + }, + { + "Name": "Transact-SQL", + "Aliases": [ + "t-sql", + "tsql" + ] + }, + { + "Name": "Turing", + "Aliases": [ + "tu", + "turing" + ] + }, + { + "Name": "Turtle", + "Aliases": [ + "ttl", + "turtle" + ] + }, + { + "Name": "Twig", + "Aliases": [ + "twig" + ] + }, + { + "Name": "TypeScript", + "Aliases": [ + "ts", + "tsx", + "typescript" + ] + }, + { + "Name": "TypoScript", + "Aliases": [ + "ts", + "typoscript" + ] + }, + { + "Name": "TypoScriptCssData", + "Aliases": [ + "typoscriptcssdata" + ] + }, + { + "Name": "TypoScriptHtmlData", + "Aliases": [ + "typoscripthtmldata" + ] + }, + { + "Name": "VB.net", + "Aliases": [ + "bas", + "vb", + "vb.net", + "vbnet" + ] + }, + { + "Name": "verilog", + "Aliases": [ + "v", + "verilog" + ] + }, + { + "Name": "VHDL", + "Aliases": [ + "vhd", + "vhdl" + ] + }, + { + "Name": "VimL", + "Aliases": [ + "exrc", + "gvimrc", + "vim", + "vimrc" + ] + }, + { + "Name": "vue", + "Aliases": [ + "vue", + "vuejs" + ] + }, + { + "Name": "WDTE", + "Aliases": [ + "wdte" + ] + }, + { + "Name": "XML", + "Aliases": [ + "csproj", + "fsproj", + "rss", + "svg", + "vcxproj", + "wsdl", + "wsf", + "xml", + "xsd", + "xsl", + "xslt" + ] + }, + { + "Name": "Xorg", + "Aliases": [ + "conf", + "xorg.conf" + ] + }, + { + "Name": "YAML", + "Aliases": [ + "yaml", + "yml" + ] + }, + { + "Name": "YANG", + "Aliases": [ + "yang" + ] + }, + { + "Name": "Zed", + "Aliases": [ + "zed" + ] + }, + { + "Name": "Zig", + "Aliases": [ + "zig" + ] + } + ] + }, + "config": { + "markup": { + "defaultMarkdownHandler": "goldmark", + "highlight": { + "style": "monokai", + "codeFences": true, + "noClasses": true, + "noHl": false, + "lineNos": false, + "lineNumbersInTable": true, + "anchorLineNos": false, + "lineAnchors": "", + "lineNoStart": 1, + "hl_Lines": "", + "tabWidth": 4, + "guessSyntax": false + }, + "tableOfContents": { + "startLevel": 2, + "endLevel": 3, + "ordered": false + }, + "goldmark": { + "renderer": { + "hardWraps": false, + "xhtml": false, + "unsafe": false + }, + "parser": { + "autoHeadingID": true, + "autoHeadingIDType": "github", + "attribute": { + "title": true, + "block": false + } + }, + "extensions": { + "typographer": true, + "footnote": true, + "definitionList": true, + "table": true, + "strikethrough": true, + "linkify": true, + "taskList": true + } + }, + "blackFriday": { + "smartypants": true, + "smartypantsQuotesNBSP": false, + "angledQuotes": false, + "fractions": true, + "hrefTargetBlank": false, + "nofollowLinks": false, + "noreferrerLinks": false, + "smartDashes": true, + "latexDashes": true, + "taskLists": true, + "plainIDAnchors": true, + "extensions": null, + "extensionsMask": null, + "skipHTML": false, + "footnoteAnchorPrefix": "", + "footnoteReturnLinkContents": "" + }, + "asciidocExt": { + "backend": "html5", + "extensions": [], + "attributes": {}, + "noHeaderOrFooter": true, + "safeMode": "unsafe", + "sectionNumbers": false, + "verbose": false, + "trace": false, + "failureLevel": "fatal", + "workingFolderCurrent": false, + "preserveTOC": false + } + }, + "mergeStrategy": { + "build": { + "_merge": "none" + }, + "caches": { + "_merge": "none" + }, + "cascade": { + "_merge": "none" + }, + "frontmatter": { + "_merge": "none" + }, + "imaging": { + "_merge": "none" + }, + "languages": { + "_merge": "none", + "en": { + "_merge": "none", + "menus": { + "_merge": "shallow" + }, + "params": { + "_merge": "deep" + } + } + }, + "markup": { + "_merge": "none" + }, + "mediatypes": { + "_merge": "shallow" + }, + "menus": { + "_merge": "shallow" + }, + "minify": { + "_merge": "none" + }, + "module": { + "_merge": "none" + }, + "outputformats": { + "_merge": "shallow" + }, + "params": { + "_merge": "deep" + }, + "permalinks": { + "_merge": "none" + }, + "privacy": { + "_merge": "none" + }, + "related": { + "_merge": "none" + }, + "security": { + "_merge": "none" + }, + "sitemap": { + "_merge": "none" + }, + "taxonomies": { + "_merge": "none" + } + }, + "minify": { + "minifyOutput": false, + "disableHTML": false, + "disableCSS": false, + "disableJS": false, + "disableJSON": false, + "disableSVG": false, + "disableXML": false, + "tdewolff": { + "html": { + "keepComments": false, + "keepConditionalComments": true, + "keepDefaultAttrVals": true, + "keepDocumentTags": true, + "keepEndTags": true, + "keepQuotes": false, + "keepWhitespace": true + }, + "css": { + "keepCSS2": true, + "precision": 0 + }, + "js": { + "precision": 0, + "keepVarNames": false, + "noNullishOperator": false + }, + "json": { + "precision": 0, + "keepNumbers": false + }, + "svg": { + "precision": 0 + }, + "xml": { + "keepWhitespace": false + } + } + }, + "security": { + "enableInlineShortcodes": false, + "exec": { + "allow": [ + "^dart-sass-embedded$", + "^go$", + "^npx$", + "^postcss$" + ], + "osEnv": [ + "(?i)^(PATH|PATHEXT|APPDATA|TMP|TEMP|TERM)$" + ] + }, + "funcs": { + "getenv": [ + "^HUGO_" + ] + }, + "http": { + "methods": [ + "(?i)GET|POST" + ], + "urls": [ + ".*" + ] + } + } + }, + "media": { + "types": [ + { + "mainType": "application", + "subType": "javascript", + "delimiter": ".", + "firstSuffix": { + "suffix": "js", + "fullSuffix": ".js" + }, + "type": "application/javascript", + "string": "application/javascript", + "suffixes": [ + "js", + "jsm", + "mjs" + ] + }, + { + "mainType": "application", + "subType": "json", + "delimiter": ".", + "firstSuffix": { + "suffix": "json", + "fullSuffix": ".json" + }, + "type": "application/json", + "string": "application/json", + "suffixes": [ + "json" + ] + }, + { + "mainType": "application", + "subType": "manifest", + "delimiter": ".", + "firstSuffix": { + "suffix": "webmanifest", + "fullSuffix": ".webmanifest" + }, + "type": "application/manifest+json", + "string": "application/manifest+json", + "suffixes": [ + "webmanifest" + ] + }, + { + "mainType": "application", + "subType": "octet-stream", + "delimiter": ".", + "firstSuffix": { + "suffix": "", + "fullSuffix": "" + }, + "type": "application/octet-stream", + "string": "application/octet-stream", + "suffixes": [ + "" + ] + }, + { + "mainType": "application", + "subType": "pdf", + "delimiter": ".", + "firstSuffix": { + "suffix": "pdf", + "fullSuffix": ".pdf" + }, + "type": "application/pdf", + "string": "application/pdf", + "suffixes": [ + "pdf" + ] + }, + { + "mainType": "application", + "subType": "rss", + "delimiter": ".", + "firstSuffix": { + "suffix": "xml", + "fullSuffix": ".xml" + }, + "type": "application/rss+xml", + "string": "application/rss+xml", + "suffixes": [ + "xml", + "rss" + ] + }, + { + "mainType": "application", + "subType": "toml", + "delimiter": ".", + "firstSuffix": { + "suffix": "toml", + "fullSuffix": ".toml" + }, + "type": "application/toml", + "string": "application/toml", + "suffixes": [ + "toml" + ] + }, + { + "mainType": "application", + "subType": "typescript", + "delimiter": ".", + "firstSuffix": { + "suffix": "ts", + "fullSuffix": ".ts" + }, + "type": "application/typescript", + "string": "application/typescript", + "suffixes": [ + "ts" + ] + }, + { + "mainType": "application", + "subType": "xml", + "delimiter": ".", + "firstSuffix": { + "suffix": "xml", + "fullSuffix": ".xml" + }, + "type": "application/xml", + "string": "application/xml", + "suffixes": [ + "xml" + ] + }, + { + "mainType": "application", + "subType": "yaml", + "delimiter": ".", + "firstSuffix": { + "suffix": "yaml", + "fullSuffix": ".yaml" + }, + "type": "application/yaml", + "string": "application/yaml", + "suffixes": [ + "yaml", + "yml" + ] + }, + { + "mainType": "font", + "subType": "otf", + "delimiter": ".", + "firstSuffix": { + "suffix": "otf", + "fullSuffix": ".otf" + }, + "type": "font/otf", + "string": "font/otf", + "suffixes": [ + "otf" + ] + }, + { + "mainType": "font", + "subType": "ttf", + "delimiter": ".", + "firstSuffix": { + "suffix": "ttf", + "fullSuffix": ".ttf" + }, + "type": "font/ttf", + "string": "font/ttf", + "suffixes": [ + "ttf" + ] + }, + { + "mainType": "image", + "subType": "bmp", + "delimiter": ".", + "firstSuffix": { + "suffix": "bmp", + "fullSuffix": ".bmp" + }, + "type": "image/bmp", + "string": "image/bmp", + "suffixes": [ + "bmp" + ] + }, + { + "mainType": "image", + "subType": "gif", + "delimiter": ".", + "firstSuffix": { + "suffix": "gif", + "fullSuffix": ".gif" + }, + "type": "image/gif", + "string": "image/gif", + "suffixes": [ + "gif" + ] + }, + { + "mainType": "image", + "subType": "jpeg", + "delimiter": ".", + "firstSuffix": { + "suffix": "jpg", + "fullSuffix": ".jpg" + }, + "type": "image/jpeg", + "string": "image/jpeg", + "suffixes": [ + "jpg", + "jpeg", + "jpe", + "jif", + "jfif" + ] + }, + { + "mainType": "image", + "subType": "png", + "delimiter": ".", + "firstSuffix": { + "suffix": "png", + "fullSuffix": ".png" + }, + "type": "image/png", + "string": "image/png", + "suffixes": [ + "png" + ] + }, + { + "mainType": "image", + "subType": "svg", + "delimiter": ".", + "firstSuffix": { + "suffix": "svg", + "fullSuffix": ".svg" + }, + "type": "image/svg+xml", + "string": "image/svg+xml", + "suffixes": [ + "svg" + ] + }, + { + "mainType": "image", + "subType": "webp", + "delimiter": ".", + "firstSuffix": { + "suffix": "webp", + "fullSuffix": ".webp" + }, + "type": "image/webp", + "string": "image/webp", + "suffixes": [ + "webp" + ] + }, + { + "mainType": "text", + "subType": "calendar", + "delimiter": ".", + "firstSuffix": { + "suffix": "ics", + "fullSuffix": ".ics" + }, + "type": "text/calendar", + "string": "text/calendar", + "suffixes": [ + "ics" + ] + }, + { + "mainType": "text", + "subType": "css", + "delimiter": ".", + "firstSuffix": { + "suffix": "css", + "fullSuffix": ".css" + }, + "type": "text/css", + "string": "text/css", + "suffixes": [ + "css" + ] + }, + { + "mainType": "text", + "subType": "csv", + "delimiter": ".", + "firstSuffix": { + "suffix": "csv", + "fullSuffix": ".csv" + }, + "type": "text/csv", + "string": "text/csv", + "suffixes": [ + "csv" + ] + }, + { + "mainType": "text", + "subType": "html", + "delimiter": ".", + "firstSuffix": { + "suffix": "html", + "fullSuffix": ".html" + }, + "type": "text/html", + "string": "text/html", + "suffixes": [ + "html" + ] + }, + { + "mainType": "text", + "subType": "jsx", + "delimiter": ".", + "firstSuffix": { + "suffix": "jsx", + "fullSuffix": ".jsx" + }, + "type": "text/jsx", + "string": "text/jsx", + "suffixes": [ + "jsx" + ] + }, + { + "mainType": "text", + "subType": "plain", + "delimiter": ".", + "firstSuffix": { + "suffix": "txt", + "fullSuffix": ".txt" + }, + "type": "text/plain", + "string": "text/plain", + "suffixes": [ + "txt" + ] + }, + { + "mainType": "text", + "subType": "tsx", + "delimiter": ".", + "firstSuffix": { + "suffix": "tsx", + "fullSuffix": ".tsx" + }, + "type": "text/tsx", + "string": "text/tsx", + "suffixes": [ + "tsx" + ] + }, + { + "mainType": "text", + "subType": "x-sass", + "delimiter": ".", + "firstSuffix": { + "suffix": "sass", + "fullSuffix": ".sass" + }, + "type": "text/x-sass", + "string": "text/x-sass", + "suffixes": [ + "sass" + ] + }, + { + "mainType": "text", + "subType": "x-scss", + "delimiter": ".", + "firstSuffix": { + "suffix": "scss", + "fullSuffix": ".scss" + }, + "type": "text/x-scss", + "string": "text/x-scss", + "suffixes": [ + "scss" + ] + }, + { + "mainType": "video", + "subType": "3gpp", + "delimiter": ".", + "firstSuffix": { + "suffix": "3gpp", + "fullSuffix": ".3gpp" + }, + "type": "video/3gpp", + "string": "video/3gpp", + "suffixes": [ + "3gpp", + "3gp" + ] + }, + { + "mainType": "video", + "subType": "mp4", + "delimiter": ".", + "firstSuffix": { + "suffix": "mp4", + "fullSuffix": ".mp4" + }, + "type": "video/mp4", + "string": "video/mp4", + "suffixes": [ + "mp4" + ] + }, + { + "mainType": "video", + "subType": "mpeg", + "delimiter": ".", + "firstSuffix": { + "suffix": "mpg", + "fullSuffix": ".mpg" + }, + "type": "video/mpeg", + "string": "video/mpeg", + "suffixes": [ + "mpg", + "mpeg" + ] + }, + { + "mainType": "video", + "subType": "ogg", + "delimiter": ".", + "firstSuffix": { + "suffix": "ogv", + "fullSuffix": ".ogv" + }, + "type": "video/ogg", + "string": "video/ogg", + "suffixes": [ + "ogv" + ] + }, + { + "mainType": "video", + "subType": "webm", + "delimiter": ".", + "firstSuffix": { + "suffix": "webm", + "fullSuffix": ".webm" + }, + "type": "video/webm", + "string": "video/webm", + "suffixes": [ + "webm" + ] + }, + { + "mainType": "video", + "subType": "x-msvideo", + "delimiter": ".", + "firstSuffix": { + "suffix": "avi", + "fullSuffix": ".avi" + }, + "type": "video/x-msvideo", + "string": "video/x-msvideo", + "suffixes": [ + "avi" + ] + } + ] + }, + "output": { + "formats": [ + { + "mediaType": "text/html", + "name": "HTML", + "path": "", + "baseName": "index", + "rel": "canonical", + "protocol": "", + "isPlainText": false, + "isHTML": true, + "noUgly": false, + "notAlternative": false, + "permalinkable": true, + "weight": 10 + }, + { + "mediaType": "text/html", + "name": "AMP", + "path": "amp", + "baseName": "index", + "rel": "amphtml", + "protocol": "", + "isPlainText": false, + "isHTML": true, + "noUgly": false, + "notAlternative": false, + "permalinkable": true, + "weight": 0 + }, + { + "mediaType": "text/css", + "name": "CSS", + "path": "", + "baseName": "styles", + "rel": "stylesheet", + "protocol": "", + "isPlainText": true, + "isHTML": false, + "noUgly": false, + "notAlternative": true, + "permalinkable": false, + "weight": 0 + }, + { + "mediaType": "text/csv", + "name": "CSV", + "path": "", + "baseName": "index", + "rel": "alternate", + "protocol": "", + "isPlainText": true, + "isHTML": false, + "noUgly": false, + "notAlternative": false, + "permalinkable": false, + "weight": 0 + }, + { + "mediaType": "text/calendar", + "name": "Calendar", + "path": "", + "baseName": "index", + "rel": "alternate", + "protocol": "webcal://", + "isPlainText": true, + "isHTML": false, + "noUgly": false, + "notAlternative": false, + "permalinkable": false, + "weight": 0 + }, + { + "mediaType": "application/json", + "name": "JSON", + "path": "", + "baseName": "index", + "rel": "alternate", + "protocol": "", + "isPlainText": true, + "isHTML": false, + "noUgly": false, + "notAlternative": false, + "permalinkable": false, + "weight": 0 + }, + { + "mediaType": "text/plain", + "name": "ROBOTS", + "path": "", + "baseName": "robots", + "rel": "alternate", + "protocol": "", + "isPlainText": true, + "isHTML": false, + "noUgly": false, + "notAlternative": false, + "permalinkable": false, + "weight": 0 + }, + { + "mediaType": "application/rss+xml", + "name": "RSS", + "path": "", + "baseName": "index", + "rel": "alternate", + "protocol": "", + "isPlainText": false, + "isHTML": false, + "noUgly": true, + "notAlternative": false, + "permalinkable": false, + "weight": 0 + }, + { + "mediaType": "application/xml", + "name": "Sitemap", + "path": "", + "baseName": "sitemap", + "rel": "sitemap", + "protocol": "", + "isPlainText": false, + "isHTML": false, + "noUgly": true, + "notAlternative": false, + "permalinkable": false, + "weight": 0 + }, + { + "mediaType": "application/manifest+json", + "name": "WebAppManifest", + "path": "", + "baseName": "manifest", + "rel": "manifest", + "protocol": "", + "isPlainText": true, + "isHTML": false, + "noUgly": false, + "notAlternative": true, + "permalinkable": false, + "weight": 0 + } + ], + "layouts": [ + { + "Example": "Single page in \"posts\" section", + "Kind": "page", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/posts/single.html.html", + "layouts/posts/single.html", + "layouts/_default/single.html.html", + "layouts/_default/single.html" + ] + }, + { + "Example": "Base template for single page in \"posts\" section", + "Kind": "page", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/posts/single-baseof.html.html", + "layouts/posts/baseof.html.html", + "layouts/posts/single-baseof.html", + "layouts/posts/baseof.html", + "layouts/_default/single-baseof.html.html", + "layouts/_default/baseof.html.html", + "layouts/_default/single-baseof.html", + "layouts/_default/baseof.html" + ] + }, + { + "Example": "Single page in \"posts\" section with layout set", + "Kind": "page", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/posts/demolayout.html.html", + "layouts/posts/single.html.html", + "layouts/posts/demolayout.html", + "layouts/posts/single.html", + "layouts/_default/demolayout.html.html", + "layouts/_default/single.html.html", + "layouts/_default/demolayout.html", + "layouts/_default/single.html" + ] + }, + { + "Example": "Base template for single page in \"posts\" section with layout set", + "Kind": "page", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/posts/demolayout-baseof.html.html", + "layouts/posts/single-baseof.html.html", + "layouts/posts/baseof.html.html", + "layouts/posts/demolayout-baseof.html", + "layouts/posts/single-baseof.html", + "layouts/posts/baseof.html", + "layouts/_default/demolayout-baseof.html.html", + "layouts/_default/single-baseof.html.html", + "layouts/_default/baseof.html.html", + "layouts/_default/demolayout-baseof.html", + "layouts/_default/single-baseof.html", + "layouts/_default/baseof.html" + ] + }, + { + "Example": "AMP single page", + "Kind": "page", + "OutputFormat": "AMP", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/posts/single.amp.html", + "layouts/posts/single.html", + "layouts/_default/single.amp.html", + "layouts/_default/single.html" + ] + }, + { + "Example": "AMP single page, French language", + "Kind": "page", + "OutputFormat": "AMP", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/posts/single.fr.amp.html", + "layouts/posts/single.amp.html", + "layouts/posts/single.fr.html", + "layouts/posts/single.html", + "layouts/_default/single.fr.amp.html", + "layouts/_default/single.amp.html", + "layouts/_default/single.fr.html", + "layouts/_default/single.html" + ] + }, + { + "Example": "Home page", + "Kind": "home", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/index.html.html", + "layouts/home.html.html", + "layouts/list.html.html", + "layouts/index.html", + "layouts/home.html", + "layouts/list.html", + "layouts/_default/index.html.html", + "layouts/_default/home.html.html", + "layouts/_default/list.html.html", + "layouts/_default/index.html", + "layouts/_default/home.html", + "layouts/_default/list.html" + ] + }, + { + "Example": "Base template for home page", + "Kind": "home", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/index-baseof.html.html", + "layouts/home-baseof.html.html", + "layouts/list-baseof.html.html", + "layouts/baseof.html.html", + "layouts/index-baseof.html", + "layouts/home-baseof.html", + "layouts/list-baseof.html", + "layouts/baseof.html", + "layouts/_default/index-baseof.html.html", + "layouts/_default/home-baseof.html.html", + "layouts/_default/list-baseof.html.html", + "layouts/_default/baseof.html.html", + "layouts/_default/index-baseof.html", + "layouts/_default/home-baseof.html", + "layouts/_default/list-baseof.html", + "layouts/_default/baseof.html" + ] + }, + { + "Example": "Home page with type set", + "Kind": "home", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/demotype/index.html.html", + "layouts/demotype/home.html.html", + "layouts/demotype/list.html.html", + "layouts/demotype/index.html", + "layouts/demotype/home.html", + "layouts/demotype/list.html", + "layouts/index.html.html", + "layouts/home.html.html", + "layouts/list.html.html", + "layouts/index.html", + "layouts/home.html", + "layouts/list.html", + "layouts/_default/index.html.html", + "layouts/_default/home.html.html", + "layouts/_default/list.html.html", + "layouts/_default/index.html", + "layouts/_default/home.html", + "layouts/_default/list.html" + ] + }, + { + "Example": "Base template for home page with type set", + "Kind": "home", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/demotype/index-baseof.html.html", + "layouts/demotype/home-baseof.html.html", + "layouts/demotype/list-baseof.html.html", + "layouts/demotype/baseof.html.html", + "layouts/demotype/index-baseof.html", + "layouts/demotype/home-baseof.html", + "layouts/demotype/list-baseof.html", + "layouts/demotype/baseof.html", + "layouts/index-baseof.html.html", + "layouts/home-baseof.html.html", + "layouts/list-baseof.html.html", + "layouts/baseof.html.html", + "layouts/index-baseof.html", + "layouts/home-baseof.html", + "layouts/list-baseof.html", + "layouts/baseof.html", + "layouts/_default/index-baseof.html.html", + "layouts/_default/home-baseof.html.html", + "layouts/_default/list-baseof.html.html", + "layouts/_default/baseof.html.html", + "layouts/_default/index-baseof.html", + "layouts/_default/home-baseof.html", + "layouts/_default/list-baseof.html", + "layouts/_default/baseof.html" + ] + }, + { + "Example": "Home page with layout set", + "Kind": "home", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/demolayout.html.html", + "layouts/index.html.html", + "layouts/home.html.html", + "layouts/list.html.html", + "layouts/demolayout.html", + "layouts/index.html", + "layouts/home.html", + "layouts/list.html", + "layouts/_default/demolayout.html.html", + "layouts/_default/index.html.html", + "layouts/_default/home.html.html", + "layouts/_default/list.html.html", + "layouts/_default/demolayout.html", + "layouts/_default/index.html", + "layouts/_default/home.html", + "layouts/_default/list.html" + ] + }, + { + "Example": "AMP home, French language", + "Kind": "home", + "OutputFormat": "AMP", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/index.fr.amp.html", + "layouts/home.fr.amp.html", + "layouts/list.fr.amp.html", + "layouts/index.amp.html", + "layouts/home.amp.html", + "layouts/list.amp.html", + "layouts/index.fr.html", + "layouts/home.fr.html", + "layouts/list.fr.html", + "layouts/index.html", + "layouts/home.html", + "layouts/list.html", + "layouts/_default/index.fr.amp.html", + "layouts/_default/home.fr.amp.html", + "layouts/_default/list.fr.amp.html", + "layouts/_default/index.amp.html", + "layouts/_default/home.amp.html", + "layouts/_default/list.amp.html", + "layouts/_default/index.fr.html", + "layouts/_default/home.fr.html", + "layouts/_default/list.fr.html", + "layouts/_default/index.html", + "layouts/_default/home.html", + "layouts/_default/list.html" + ] + }, + { + "Example": "JSON home", + "Kind": "home", + "OutputFormat": "JSON", + "Suffix": "json", + "Template Lookup Order": [ + "layouts/index.json.json", + "layouts/home.json.json", + "layouts/list.json.json", + "layouts/index.json", + "layouts/home.json", + "layouts/list.json", + "layouts/_default/index.json.json", + "layouts/_default/home.json.json", + "layouts/_default/list.json.json", + "layouts/_default/index.json", + "layouts/_default/home.json", + "layouts/_default/list.json" + ] + }, + { + "Example": "RSS home", + "Kind": "home", + "OutputFormat": "RSS", + "Suffix": "xml", + "Template Lookup Order": [ + "layouts/index.rss.xml", + "layouts/home.rss.xml", + "layouts/rss.xml", + "layouts/list.rss.xml", + "layouts/index.xml", + "layouts/home.xml", + "layouts/list.xml", + "layouts/_default/index.rss.xml", + "layouts/_default/home.rss.xml", + "layouts/_default/rss.xml", + "layouts/_default/list.rss.xml", + "layouts/_default/index.xml", + "layouts/_default/home.xml", + "layouts/_default/list.xml", + "layouts/_internal/_default/rss.xml" + ] + }, + { + "Example": "RSS section posts", + "Kind": "section", + "OutputFormat": "RSS", + "Suffix": "xml", + "Template Lookup Order": [ + "layouts/posts/section.rss.xml", + "layouts/posts/rss.xml", + "layouts/posts/list.rss.xml", + "layouts/posts/section.xml", + "layouts/posts/list.xml", + "layouts/section/section.rss.xml", + "layouts/section/rss.xml", + "layouts/section/list.rss.xml", + "layouts/section/section.xml", + "layouts/section/list.xml", + "layouts/_default/section.rss.xml", + "layouts/_default/rss.xml", + "layouts/_default/list.rss.xml", + "layouts/_default/section.xml", + "layouts/_default/list.xml", + "layouts/_internal/_default/rss.xml" + ] + }, + { + "Example": "Taxonomy in categories", + "Kind": "taxonomy", + "OutputFormat": "RSS", + "Suffix": "xml", + "Template Lookup Order": [ + "layouts/categories/category.terms.rss.xml", + "layouts/categories/terms.rss.xml", + "layouts/categories/taxonomy.rss.xml", + "layouts/categories/rss.xml", + "layouts/categories/list.rss.xml", + "layouts/categories/category.terms.xml", + "layouts/categories/terms.xml", + "layouts/categories/taxonomy.xml", + "layouts/categories/list.xml", + "layouts/category/category.terms.rss.xml", + "layouts/category/terms.rss.xml", + "layouts/category/taxonomy.rss.xml", + "layouts/category/rss.xml", + "layouts/category/list.rss.xml", + "layouts/category/category.terms.xml", + "layouts/category/terms.xml", + "layouts/category/taxonomy.xml", + "layouts/category/list.xml", + "layouts/taxonomy/category.terms.rss.xml", + "layouts/taxonomy/terms.rss.xml", + "layouts/taxonomy/taxonomy.rss.xml", + "layouts/taxonomy/rss.xml", + "layouts/taxonomy/list.rss.xml", + "layouts/taxonomy/category.terms.xml", + "layouts/taxonomy/terms.xml", + "layouts/taxonomy/taxonomy.xml", + "layouts/taxonomy/list.xml", + "layouts/_default/category.terms.rss.xml", + "layouts/_default/terms.rss.xml", + "layouts/_default/taxonomy.rss.xml", + "layouts/_default/rss.xml", + "layouts/_default/list.rss.xml", + "layouts/_default/category.terms.xml", + "layouts/_default/terms.xml", + "layouts/_default/taxonomy.xml", + "layouts/_default/list.xml", + "layouts/_internal/_default/rss.xml" + ] + }, + { + "Example": "Term in categories", + "Kind": "term", + "OutputFormat": "RSS", + "Suffix": "xml", + "Template Lookup Order": [ + "layouts/categories/term.rss.xml", + "layouts/categories/category.rss.xml", + "layouts/categories/taxonomy.rss.xml", + "layouts/categories/rss.xml", + "layouts/categories/list.rss.xml", + "layouts/categories/term.xml", + "layouts/categories/category.xml", + "layouts/categories/taxonomy.xml", + "layouts/categories/list.xml", + "layouts/term/term.rss.xml", + "layouts/term/category.rss.xml", + "layouts/term/taxonomy.rss.xml", + "layouts/term/rss.xml", + "layouts/term/list.rss.xml", + "layouts/term/term.xml", + "layouts/term/category.xml", + "layouts/term/taxonomy.xml", + "layouts/term/list.xml", + "layouts/taxonomy/term.rss.xml", + "layouts/taxonomy/category.rss.xml", + "layouts/taxonomy/taxonomy.rss.xml", + "layouts/taxonomy/rss.xml", + "layouts/taxonomy/list.rss.xml", + "layouts/taxonomy/term.xml", + "layouts/taxonomy/category.xml", + "layouts/taxonomy/taxonomy.xml", + "layouts/taxonomy/list.xml", + "layouts/category/term.rss.xml", + "layouts/category/category.rss.xml", + "layouts/category/taxonomy.rss.xml", + "layouts/category/rss.xml", + "layouts/category/list.rss.xml", + "layouts/category/term.xml", + "layouts/category/category.xml", + "layouts/category/taxonomy.xml", + "layouts/category/list.xml", + "layouts/_default/term.rss.xml", + "layouts/_default/category.rss.xml", + "layouts/_default/taxonomy.rss.xml", + "layouts/_default/rss.xml", + "layouts/_default/list.rss.xml", + "layouts/_default/term.xml", + "layouts/_default/category.xml", + "layouts/_default/taxonomy.xml", + "layouts/_default/list.xml", + "layouts/_internal/_default/rss.xml" + ] + }, + { + "Example": "Section list for \"posts\" section", + "Kind": "section", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/posts/posts.html.html", + "layouts/posts/section.html.html", + "layouts/posts/list.html.html", + "layouts/posts/posts.html", + "layouts/posts/section.html", + "layouts/posts/list.html", + "layouts/section/posts.html.html", + "layouts/section/section.html.html", + "layouts/section/list.html.html", + "layouts/section/posts.html", + "layouts/section/section.html", + "layouts/section/list.html", + "layouts/_default/posts.html.html", + "layouts/_default/section.html.html", + "layouts/_default/list.html.html", + "layouts/_default/posts.html", + "layouts/_default/section.html", + "layouts/_default/list.html" + ] + }, + { + "Example": "Section list for \"posts\" section with type set to \"blog\"", + "Kind": "section", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/blog/posts.html.html", + "layouts/blog/section.html.html", + "layouts/blog/list.html.html", + "layouts/blog/posts.html", + "layouts/blog/section.html", + "layouts/blog/list.html", + "layouts/posts/posts.html.html", + "layouts/posts/section.html.html", + "layouts/posts/list.html.html", + "layouts/posts/posts.html", + "layouts/posts/section.html", + "layouts/posts/list.html", + "layouts/section/posts.html.html", + "layouts/section/section.html.html", + "layouts/section/list.html.html", + "layouts/section/posts.html", + "layouts/section/section.html", + "layouts/section/list.html", + "layouts/_default/posts.html.html", + "layouts/_default/section.html.html", + "layouts/_default/list.html.html", + "layouts/_default/posts.html", + "layouts/_default/section.html", + "layouts/_default/list.html" + ] + }, + { + "Example": "Section list for \"posts\" section with layout set to \"demoLayout\"", + "Kind": "section", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/posts/demolayout.html.html", + "layouts/posts/posts.html.html", + "layouts/posts/section.html.html", + "layouts/posts/list.html.html", + "layouts/posts/demolayout.html", + "layouts/posts/posts.html", + "layouts/posts/section.html", + "layouts/posts/list.html", + "layouts/section/demolayout.html.html", + "layouts/section/posts.html.html", + "layouts/section/section.html.html", + "layouts/section/list.html.html", + "layouts/section/demolayout.html", + "layouts/section/posts.html", + "layouts/section/section.html", + "layouts/section/list.html", + "layouts/_default/demolayout.html.html", + "layouts/_default/posts.html.html", + "layouts/_default/section.html.html", + "layouts/_default/list.html.html", + "layouts/_default/demolayout.html", + "layouts/_default/posts.html", + "layouts/_default/section.html", + "layouts/_default/list.html" + ] + }, + { + "Example": "Taxonomy list in categories", + "Kind": "taxonomy", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/categories/category.terms.html.html", + "layouts/categories/terms.html.html", + "layouts/categories/taxonomy.html.html", + "layouts/categories/list.html.html", + "layouts/categories/category.terms.html", + "layouts/categories/terms.html", + "layouts/categories/taxonomy.html", + "layouts/categories/list.html", + "layouts/category/category.terms.html.html", + "layouts/category/terms.html.html", + "layouts/category/taxonomy.html.html", + "layouts/category/list.html.html", + "layouts/category/category.terms.html", + "layouts/category/terms.html", + "layouts/category/taxonomy.html", + "layouts/category/list.html", + "layouts/taxonomy/category.terms.html.html", + "layouts/taxonomy/terms.html.html", + "layouts/taxonomy/taxonomy.html.html", + "layouts/taxonomy/list.html.html", + "layouts/taxonomy/category.terms.html", + "layouts/taxonomy/terms.html", + "layouts/taxonomy/taxonomy.html", + "layouts/taxonomy/list.html", + "layouts/_default/category.terms.html.html", + "layouts/_default/terms.html.html", + "layouts/_default/taxonomy.html.html", + "layouts/_default/list.html.html", + "layouts/_default/category.terms.html", + "layouts/_default/terms.html", + "layouts/_default/taxonomy.html", + "layouts/_default/list.html" + ] + }, + { + "Example": "Taxonomy term in categories", + "Kind": "term", + "OutputFormat": "HTML", + "Suffix": "html", + "Template Lookup Order": [ + "layouts/categories/term.html.html", + "layouts/categories/category.html.html", + "layouts/categories/taxonomy.html.html", + "layouts/categories/list.html.html", + "layouts/categories/term.html", + "layouts/categories/category.html", + "layouts/categories/taxonomy.html", + "layouts/categories/list.html", + "layouts/term/term.html.html", + "layouts/term/category.html.html", + "layouts/term/taxonomy.html.html", + "layouts/term/list.html.html", + "layouts/term/term.html", + "layouts/term/category.html", + "layouts/term/taxonomy.html", + "layouts/term/list.html", + "layouts/taxonomy/term.html.html", + "layouts/taxonomy/category.html.html", + "layouts/taxonomy/taxonomy.html.html", + "layouts/taxonomy/list.html.html", + "layouts/taxonomy/term.html", + "layouts/taxonomy/category.html", + "layouts/taxonomy/taxonomy.html", + "layouts/taxonomy/list.html", + "layouts/category/term.html.html", + "layouts/category/category.html.html", + "layouts/category/taxonomy.html.html", + "layouts/category/list.html.html", + "layouts/category/term.html", + "layouts/category/category.html", + "layouts/category/taxonomy.html", + "layouts/category/list.html", + "layouts/_default/term.html.html", + "layouts/_default/category.html.html", + "layouts/_default/taxonomy.html.html", + "layouts/_default/list.html.html", + "layouts/_default/term.html", + "layouts/_default/category.html", + "layouts/_default/taxonomy.html", + "layouts/_default/list.html" + ] + } + ] + }, + "tpl": { + "funcs": { + "cast": { + "ToFloat": { + "Description": "ToFloat converts the given value to a float.", + "Args": [ + "v" + ], + "Aliases": [ + "float" + ], + "Examples": [ + [ + "{{ \"1234\" | float | printf \"%T\" }}", + "float64" + ] + ] + }, + "ToInt": { + "Description": "ToInt converts the given value to an int.", + "Args": [ + "v" + ], + "Aliases": [ + "int" + ], + "Examples": [ + [ + "{{ \"1234\" | int | printf \"%T\" }}", + "int" + ] + ] + }, + "ToString": { + "Description": "ToString converts the given value to a string.", + "Args": [ + "v" + ], + "Aliases": [ + "string" + ], + "Examples": [ + [ + "{{ 1234 | string | printf \"%T\" }}", + "string" + ] + ] + } + }, + "compare": { + "Conditional": { + "Description": "Conditional can be used as a ternary operator.\nIt returns a if condition, else b.", + "Args": [ + "condition", + "a", + "b" + ], + "Aliases": [ + "cond" + ], + "Examples": [ + [ + "{{ cond (eq (add 2 2) 4) \"2+2 is 4\" \"what?\" | safeHTML }}", + "2+2 is 4" + ] + ] + }, + "Default": { + "Description": "Default checks whether a given value is set and returns a default value if it\nis not. \"Set\" in this context means non-zero for numeric types and times;\nnon-zero length for strings, arrays, slices, and maps;\nany boolean or struct value; or non-nil for any other types.", + "Args": [ + "dflt", + "given" + ], + "Aliases": [ + "default" + ], + "Examples": [ + [ + "{{ \"Hugo Rocks!\" | default \"Hugo Rules!\" }}", + "Hugo Rocks!" + ], + [ + "{{ \"\" | default \"Hugo Rules!\" }}", + "Hugo Rules!" + ] + ] + }, + "Eq": { + "Description": "Eq returns the boolean truth of arg1 == arg2 || arg1 == arg3 || arg1 == arg4.", + "Args": [ + "first", + "others" + ], + "Aliases": [ + "eq" + ], + "Examples": [ + [ + "{{ if eq .Section \"blog\" }}current-section{{ end }}", + "current-section" + ] + ] + }, + "Ge": { + "Description": "Ge returns the boolean truth of arg1 \u003e= arg2 \u0026\u0026 arg1 \u003e= arg3 \u0026\u0026 arg1 \u003e= arg4.", + "Args": [ + "first", + "others" + ], + "Aliases": [ + "ge" + ], + "Examples": [ + [ + "{{ if ge hugo.Version \"0.80\" }}Reasonable new Hugo version!{{ end }}", + "Reasonable new Hugo version!" + ] + ] + }, + "Gt": { + "Description": "Gt returns the boolean truth of arg1 \u003e arg2 \u0026\u0026 arg1 \u003e arg3 \u0026\u0026 arg1 \u003e arg4.", + "Args": [ + "first", + "others" + ], + "Aliases": [ + "gt" + ], + "Examples": [] + }, + "Le": { + "Description": "Le returns the boolean truth of arg1 \u003c= arg2 \u0026\u0026 arg1 \u003c= arg3 \u0026\u0026 arg1 \u003c= arg4.", + "Args": [ + "first", + "others" + ], + "Aliases": [ + "le" + ], + "Examples": [] + }, + "Lt": { + "Description": "Lt returns the boolean truth of arg1 \u003c arg2 \u0026\u0026 arg1 \u003c arg3 \u0026\u0026 arg1 \u003c arg4.", + "Args": [ + "first", + "others" + ], + "Aliases": [ + "lt" + ], + "Examples": [] + }, + "Ne": { + "Description": "Ne returns the boolean truth of arg1 != arg2 \u0026\u0026 arg1 != arg3 \u0026\u0026 arg1 != arg4.", + "Args": [ + "first", + "others" + ], + "Aliases": [ + "ne" + ], + "Examples": [] + } + }, + "collections": { + "After": { + "Description": "After returns all the items after the first num in seq.", + "Args": [ + "num", + "seq" + ], + "Aliases": [ + "after" + ], + "Examples": [] + }, + "Append": { + "Description": "Append appends the arguments up to the last one to the slice in the last argument.\nThis construct allows template constructs like this:\n {{ $pages = $pages | append $p2 $p1 }}\nNote that with 2 arguments where both are slices of the same type,\nthe first slice will be appended to the second:\n {{ $pages = $pages | append .Site.RegularPages }}", + "Args": [ + "args" + ], + "Aliases": [ + "append" + ], + "Examples": [] + }, + "Apply": { + "Description": "Apply takes a map, array, or slice and returns a new slice with the function fname applied over it.", + "Args": [ + "ctx", + "seq", + "fname", + "args" + ], + "Aliases": [ + "apply" + ], + "Examples": [] + }, + "Complement": { + "Description": "Complement gives the elements in the last element of seqs that are not in\nany of the others.\nAll elements of seqs must be slices or arrays of comparable types.\n\nThe reasoning behind this rather clumsy API is so we can do this in the templates:\n {{ $c := .Pages | complement $last4 }}", + "Args": [ + "seqs" + ], + "Aliases": [ + "complement" + ], + "Examples": [ + [ + "{{ slice \"a\" \"b\" \"c\" \"d\" \"e\" \"f\" | complement (slice \"b\" \"c\") (slice \"d\" \"e\") }}", + "[a f]" + ] + ] + }, + "Delimit": { + "Description": "Delimit takes a given sequence and returns a delimited HTML string.\nIf last is passed to the function, it will be used as the final delimiter.", + "Args": [ + "seq", + "delimiter", + "last" + ], + "Aliases": [ + "delimit" + ], + "Examples": [ + [ + "{{ delimit (slice \"A\" \"B\" \"C\") \", \" \" and \" }}", + "A, B and C" + ] + ] + }, + "Dictionary": { + "Description": "Dictionary creates a map[string]interface{} from the given parameters by\nwalking the parameters and treating them as key-value pairs. The number\nof parameters must be even.\nThe keys can be string slices, which will create the needed nested structure.", + "Args": [ + "values" + ], + "Aliases": [ + "dict" + ], + "Examples": [] + }, + "EchoParam": { + "Description": "EchoParam returns a given value if it is set; otherwise, it returns an\nempty string.", + "Args": [ + "a", + "key" + ], + "Aliases": [ + "echoParam" + ], + "Examples": [ + [ + "{{ echoParam .Params \"langCode\" }}", + "en" + ] + ] + }, + "First": { + "Description": "First returns the first N items in a rangeable list.", + "Args": [ + "limit", + "seq" + ], + "Aliases": [ + "first" + ], + "Examples": [] + }, + "Group": { + "Description": "Group groups a set of elements by the given key.\nThis is currently only supported for Pages.", + "Args": [ + "key", + "items" + ], + "Aliases": [ + "group" + ], + "Examples": [] + }, + "In": { + "Description": "In returns whether v is in the set l. l may be an array or slice.", + "Args": [ + "l", + "v" + ], + "Aliases": [ + "in" + ], + "Examples": [ + [ + "{{ if in \"this string contains a substring\" \"substring\" }}Substring found!{{ end }}", + "Substring found!" + ] + ] + }, + "Index": { + "Description": "Index returns the result of indexing its first argument by the following\narguments. Thus \"index x 1 2 3\" is, in Go syntax, x[1][2][3]. Each\nindexed item must be a map, slice, or array.\n\nCopied from Go stdlib src/text/template/funcs.go.\n\nWe deviate from the stdlib due to https://github.com/golang/go/issues/14751.\n\nTODO(moorereason): merge upstream changes.", + "Args": [ + "item", + "args" + ], + "Aliases": [ + "index" + ], + "Examples": [] + }, + "Intersect": { + "Description": "Intersect returns the common elements in the given sets, l1 and l2. l1 and\nl2 must be of the same type and may be either arrays or slices.", + "Args": [ + "l1", + "l2" + ], + "Aliases": [ + "intersect" + ], + "Examples": [] + }, + "IsSet": { + "Description": "IsSet returns whether a given array, channel, slice, or map has a key\ndefined.", + "Args": [ + "a", + "key" + ], + "Aliases": [ + "isSet", + "isset" + ], + "Examples": [] + }, + "KeyVals": { + "Description": "KeyVals creates a key and values wrapper.", + "Args": [ + "key", + "vals" + ], + "Aliases": [ + "keyVals" + ], + "Examples": [ + [ + "{{ keyVals \"key\" \"a\" \"b\" }}", + "key: [a b]" + ] + ] + }, + "Last": { + "Description": "Last returns the last N items in a rangeable list.", + "Args": [ + "limit", + "seq" + ], + "Aliases": [ + "last" + ], + "Examples": [] + }, + "Merge": { + "Description": "Merge creates a copy of the final parameter and merges the preceding\nparameters into it in reverse order.\nCurrently only maps are supported. Key handling is case insensitive.", + "Args": [ + "params" + ], + "Aliases": [ + "merge" + ], + "Examples": [ + [ + "{{ dict \"title\" \"Hugo Rocks!\" | collections.Merge (dict \"title\" \"Default Title\" \"description\" \"Yes, Hugo Rocks!\") | sort }}", + "[Yes, Hugo Rocks! Hugo Rocks!]" + ], + [ + "{{ merge (dict \"title\" \"Default Title\" \"description\" \"Yes, Hugo Rocks!\") (dict \"title\" \"Hugo Rocks!\") | sort }}", + "[Yes, Hugo Rocks! Hugo Rocks!]" + ], + [ + "{{ merge (dict \"title\" \"Default Title\" \"description\" \"Yes, Hugo Rocks!\") (dict \"title\" \"Hugo Rocks!\") (dict \"extra\" \"For reals!\") | sort }}", + "[Yes, Hugo Rocks! For reals! Hugo Rocks!]" + ] + ] + }, + "NewScratch": { + "Description": "NewScratch creates a new Scratch which can be used to store values in a\nthread safe way.", + "Args": null, + "Aliases": [ + "newScratch" + ], + "Examples": [ + [ + "{{ $scratch := newScratch }}{{ $scratch.Add \"b\" 2 }}{{ $scratch.Add \"b\" 2 }}{{ $scratch.Get \"b\" }}", + "4" + ] + ] + }, + "Querify": { + "Description": "Querify encodes the given parameters in URL-encoded form (\"bar=baz\u0026foo=quux\") sorted by key.", + "Args": [ + "params" + ], + "Aliases": [ + "querify" + ], + "Examples": [ + [ + "{{ (querify \"foo\" 1 \"bar\" 2 \"baz\" \"with spaces\" \"qux\" \"this\u0026that=those\") | safeHTML }}", + "bar=2\u0026baz=with+spaces\u0026foo=1\u0026qux=this%26that%3Dthose" + ], + [ + "\u003ca href=\"https://www.google.com?{{ (querify \"q\" \"test\" \"page\" 3) | safeURL }}\"\u003eSearch\u003c/a\u003e", + "\u003ca href=\"https://www.google.com?page=3\u0026amp;q=test\"\u003eSearch\u003c/a\u003e" + ], + [ + "{{ slice \"foo\" 1 \"bar\" 2 | querify | safeHTML }}", + "bar=2\u0026foo=1" + ] + ] + }, + "Reverse": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Seq": { + "Description": "Seq creates a sequence of integers. It's named and used as GNU's seq.\n\nExamples:\n 3 =\u003e 1, 2, 3\n 1 2 4 =\u003e 1, 3\n -3 =\u003e -1, -2, -3\n 1 4 =\u003e 1, 2, 3, 4\n 1 -2 =\u003e 1, 0, -1, -2", + "Args": [ + "args" + ], + "Aliases": [ + "seq" + ], + "Examples": [ + [ + "{{ seq 3 }}", + "[1 2 3]" + ] + ] + }, + "Shuffle": { + "Description": "Shuffle returns the given rangeable list in a randomised order.", + "Args": [ + "seq" + ], + "Aliases": [ + "shuffle" + ], + "Examples": [] + }, + "Slice": { + "Description": "Slice returns a slice of all passed arguments.", + "Args": [ + "args" + ], + "Aliases": [ + "slice" + ], + "Examples": [ + [ + "{{ slice \"B\" \"C\" \"A\" | sort }}", + "[A B C]" + ] + ] + }, + "Sort": { + "Description": "Sort returns a sorted sequence.", + "Args": [ + "seq", + "args" + ], + "Aliases": [ + "sort" + ], + "Examples": [] + }, + "SymDiff": { + "Description": "SymDiff returns the symmetric difference of s1 and s2.\nArguments must be either a slice or an array of comparable types.", + "Args": [ + "s2", + "s1" + ], + "Aliases": [ + "symdiff" + ], + "Examples": [ + [ + "{{ slice 1 2 3 | symdiff (slice 3 4) }}", + "[1 2 4]" + ] + ] + }, + "Union": { + "Description": "Union returns the union of the given sets, l1 and l2. l1 and\nl2 must be of the same type and may be either arrays or slices.\nIf l1 and l2 aren't of the same type then l1 will be returned.\nIf either l1 or l2 is nil then the non-nil list will be returned.", + "Args": [ + "l1", + "l2" + ], + "Aliases": [ + "union" + ], + "Examples": [ + [ + "{{ union (slice 1 2 3) (slice 3 4 5) }}", + "[1 2 3 4 5]" + ] + ] + }, + "Uniq": { + "Description": "Uniq takes in a slice or array and returns a slice with subsequent\nduplicate elements removed.", + "Args": [ + "seq" + ], + "Aliases": [ + "uniq" + ], + "Examples": [ + [ + "{{ slice 1 2 3 2 | uniq }}", + "[1 2 3]" + ] + ] + }, + "Where": { + "Description": "Where returns a filtered subset of a given data type.", + "Args": [ + "seq", + "key", + "args" + ], + "Aliases": [ + "where" + ], + "Examples": [] + } + }, + "crypto": { + "HMAC": { + "Description": "HMAC returns a cryptographic hash that uses a key to sign a message.", + "Args": [ + "h", + "k", + "m" + ], + "Aliases": [ + "hmac" + ], + "Examples": [ + [ + "{{ hmac \"sha256\" \"Secret key\" \"Hello world, gophers!\" }}", + "b6d11b6c53830b9d87036272ca9fe9d19306b8f9d8aa07b15da27d89e6e34f40" + ] + ] + }, + "MD5": { + "Description": "MD5 hashes the given input and returns its MD5 checksum.", + "Args": [ + "in" + ], + "Aliases": [ + "md5" + ], + "Examples": [ + [ + "{{ md5 \"Hello world, gophers!\" }}", + "b3029f756f98f79e7f1b7f1d1f0dd53b" + ], + [ + "{{ crypto.MD5 \"Hello world, gophers!\" }}", + "b3029f756f98f79e7f1b7f1d1f0dd53b" + ] + ] + }, + "SHA1": { + "Description": "SHA1 hashes the given input and returns its SHA1 checksum.", + "Args": [ + "in" + ], + "Aliases": [ + "sha1" + ], + "Examples": [ + [ + "{{ sha1 \"Hello world, gophers!\" }}", + "c8b5b0e33d408246e30f53e32b8f7627a7a649d4" + ] + ] + }, + "SHA256": { + "Description": "SHA256 hashes the given input and returns its SHA256 checksum.", + "Args": [ + "in" + ], + "Aliases": [ + "sha256" + ], + "Examples": [ + [ + "{{ sha256 \"Hello world, gophers!\" }}", + "6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46" + ] + ] + } + }, + "data": { + "GetCSV": { + "Description": "GetCSV expects a data separator and one or n-parts of a URL to a resource which\ncan either be a local or a remote one.\nThe data separator can be a comma, semi-colon, pipe, etc, but only one character.\nIf you provide multiple parts for the URL they will be joined together to the final URL.\nGetCSV returns nil or a slice slice to use in a short code.", + "Args": [ + "sep", + "args" + ], + "Aliases": [ + "getCSV" + ], + "Examples": [] + }, + "GetJSON": { + "Description": "GetJSON expects one or n-parts of a URL to a resource which can either be a local or a remote one.\nIf you provide multiple parts they will be joined together to the final URL.\nGetJSON returns nil or parsed JSON to use in a short code.", + "Args": [ + "args" + ], + "Aliases": [ + "getJSON" + ], + "Examples": [] + } + }, + "debug": { + "Dump": { + "Description": "Dump returns a object dump of val as a string.\nNote that not every value passed to Dump will print so nicely, but\nwe'll improve on that. We recommend using the \"go\" Chroma lexer to format the output\nnicely.\nAlso note that the output from Dump may change from Hugo version to the next,\nso don't depend on a specific output.", + "Args": [ + "val" + ], + "Aliases": null, + "Examples": [ + [ + "{{- $m := newScratch -}}\n{{- $m.Set \"Hugo\" \"Rocks!\" -}}\n{{- $m.Values | debug.Dump | safeHTML -}}", + "map[string]interface {}{\n \"Hugo\": \"Rocks!\",\n}" + ] + ] + } + }, + "diagrams": { + "Goat": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + } + }, + "encoding": { + "Base64Decode": { + "Description": "Base64Decode returns the base64 decoding of the given content.", + "Args": [ + "content" + ], + "Aliases": [ + "base64Decode" + ], + "Examples": [ + [ + "{{ \"SGVsbG8gd29ybGQ=\" | base64Decode }}", + "Hello world" + ], + [ + "{{ 42 | base64Encode | base64Decode }}", + "42" + ] + ] + }, + "Base64Encode": { + "Description": "Base64Encode returns the base64 encoding of the given content.", + "Args": [ + "content" + ], + "Aliases": [ + "base64Encode" + ], + "Examples": [ + [ + "{{ \"Hello world\" | base64Encode }}", + "SGVsbG8gd29ybGQ=" + ] + ] + }, + "Jsonify": { + "Description": "Jsonify encodes a given object to JSON. To pretty print the JSON, pass a map\nor dictionary of options as the first argument. Supported options are\n\"prefix\" and \"indent\". Each JSON element in the output will begin on a new\nline beginning with prefix followed by one or more copies of indent according\nto the indentation nesting.", + "Args": [ + "args" + ], + "Aliases": [ + "jsonify" + ], + "Examples": [ + [ + "{{ (slice \"A\" \"B\" \"C\") | jsonify }}", + "[\"A\",\"B\",\"C\"]" + ], + [ + "{{ (slice \"A\" \"B\" \"C\") | jsonify (dict \"indent\" \" \") }}", + "[\n \"A\",\n \"B\",\n \"C\"\n]" + ] + ] + } + }, + "fmt": { + "Errorf": { + "Description": "Errorf formats according to a format specifier and logs an ERROR.\nIt returns an empty string.", + "Args": [ + "format", + "a" + ], + "Aliases": [ + "errorf" + ], + "Examples": [ + [ + "{{ errorf \"%s.\" \"failed\" }}", + "" + ] + ] + }, + "Erroridf": { + "Description": "Erroridf formats according to a format specifier and logs an ERROR and\nan information text that the error with the given ID can be suppressed in config.\nIt returns an empty string.", + "Args": [ + "id", + "format", + "a" + ], + "Aliases": [ + "erroridf" + ], + "Examples": [ + [ + "{{ erroridf \"my-err-id\" \"%s.\" \"failed\" }}", + "" + ] + ] + }, + "Print": { + "Description": "Print returns string representation of the passed arguments.", + "Args": [ + "a" + ], + "Aliases": [ + "print" + ], + "Examples": [ + [ + "{{ print \"works!\" }}", + "works!" + ] + ] + }, + "Printf": { + "Description": "Printf returns a formatted string representation of the passed arguments.", + "Args": [ + "format", + "a" + ], + "Aliases": [ + "printf" + ], + "Examples": [ + [ + "{{ printf \"%s!\" \"works\" }}", + "works!" + ] + ] + }, + "Println": { + "Description": "Println returns string representation of the passed arguments ending with a newline.", + "Args": [ + "a" + ], + "Aliases": [ + "println" + ], + "Examples": [ + [ + "{{ println \"works!\" }}", + "works!\n" + ] + ] + }, + "Warnf": { + "Description": "Warnf formats according to a format specifier and logs a WARNING.\nIt returns an empty string.", + "Args": [ + "format", + "a" + ], + "Aliases": [ + "warnf" + ], + "Examples": [ + [ + "{{ warnf \"%s.\" \"warning\" }}", + "" + ] + ] + } + }, + "hugo": { + "Deps": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Generator": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "IsExtended": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "IsProduction": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Version": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + } + }, + "images": { + "Brightness": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "ColorBalance": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Colorize": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Config": { + "Description": "Config returns the image.Config for the specified path relative to the\nworking directory.", + "Args": [ + "path" + ], + "Aliases": [ + "imageConfig" + ], + "Examples": [] + }, + "Contrast": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Filter": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Gamma": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "GaussianBlur": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Grayscale": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Hue": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Invert": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Overlay": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Pixelate": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Saturation": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Sepia": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Sigmoid": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Text": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "UnsharpMask": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + } + }, + "inflect": { + "Humanize": { + "Description": "Humanize returns the humanized form of a single parameter.\n\nIf the parameter is either an integer or a string containing an integer\nvalue, the behavior is to add the appropriate ordinal.\n\n Example: \"my-first-post\" -\u003e \"My first post\"\n Example: \"103\" -\u003e \"103rd\"\n Example: 52 -\u003e \"52nd\"", + "Args": [ + "in" + ], + "Aliases": [ + "humanize" + ], + "Examples": [ + [ + "{{ humanize \"my-first-post\" }}", + "My first post" + ], + [ + "{{ humanize \"myCamelPost\" }}", + "My camel post" + ], + [ + "{{ humanize \"52\" }}", + "52nd" + ], + [ + "{{ humanize 103 }}", + "103rd" + ] + ] + }, + "Pluralize": { + "Description": "Pluralize returns the plural form of a single word.", + "Args": [ + "in" + ], + "Aliases": [ + "pluralize" + ], + "Examples": [ + [ + "{{ \"cat\" | pluralize }}", + "cats" + ] + ] + }, + "Singularize": { + "Description": "Singularize returns the singular form of a single word.", + "Args": [ + "in" + ], + "Aliases": [ + "singularize" + ], + "Examples": [ + [ + "{{ \"cats\" | singularize }}", + "cat" + ] + ] + } + }, + "js": { + "Build": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + } + }, + "lang": { + "FormatAccounting": { + "Description": "FormatAccounting returns the currency representation of number for the given currency and precision\nfor the current language in accounting notation.\n\nThe return value is formatted with at least two decimal places.", + "Args": [ + "precision", + "currency", + "number" + ], + "Aliases": null, + "Examples": [ + [ + "{{ 512.5032 | lang.FormatAccounting 2 \"NOK\" }}", + "NOK512.50" + ] + ] + }, + "FormatCurrency": { + "Description": "FormatCurrency returns the currency representation of number for the given currency and precision\nfor the current language.\n\nThe return value is formatted with at least two decimal places.", + "Args": [ + "precision", + "currency", + "number" + ], + "Aliases": null, + "Examples": [ + [ + "{{ 512.5032 | lang.FormatCurrency 2 \"USD\" }}", + "$512.50" + ] + ] + }, + "FormatNumber": { + "Description": "FormatNumber formats number with the given precision for the current language.", + "Args": [ + "precision", + "number" + ], + "Aliases": null, + "Examples": [ + [ + "{{ 512.5032 | lang.FormatNumber 2 }}", + "512.50" + ] + ] + }, + "FormatNumberCustom": { + "Description": "FormatNumberCustom formats a number with the given precision using the\nnegative, decimal, and grouping options. The `options`\nparameter is a string consisting of `\u003cnegative\u003e \u003cdecimal\u003e \u003cgrouping\u003e`. The\ndefault `options` value is `- . ,`.\n\nNote that numbers are rounded up at 5 or greater.\nSo, with precision set to 0, 1.5 becomes `2`, and 1.4 becomes `1`.\n\nFor a simpler function that adapts to the current language, see FormatNumber.", + "Args": [ + "precision", + "number", + "options" + ], + "Aliases": null, + "Examples": [ + [ + "{{ lang.FormatNumberCustom 2 12345.6789 }}", + "12,345.68" + ], + [ + "{{ lang.FormatNumberCustom 2 12345.6789 \"- , .\" }}", + "12.345,68" + ], + [ + "{{ lang.FormatNumberCustom 6 -12345.6789 \"- .\" }}", + "-12345.678900" + ], + [ + "{{ lang.FormatNumberCustom 0 -12345.6789 \"- . ,\" }}", + "-12,346" + ], + [ + "{{ -98765.4321 | lang.FormatNumberCustom 2 }}", + "-98,765.43" + ] + ] + }, + "FormatPercent": { + "Description": "FormatPercent formats number with the given precision for the current language.\nNote that the number is assumed to be a percentage.", + "Args": [ + "precision", + "number" + ], + "Aliases": null, + "Examples": [ + [ + "{{ 512.5032 | lang.FormatPercent 2 }}", + "512.50%" + ] + ] + }, + "Merge": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "NumFmt": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Translate": { + "Description": "Translate returns a translated string for id.", + "Args": [ + "id", + "args" + ], + "Aliases": [ + "i18n", + "T" + ], + "Examples": [] + } + }, + "math": { + "Add": { + "Description": "Add adds the two numbers num1 and num2.", + "Args": [ + "num1", + "num2" + ], + "Aliases": [ + "add" + ], + "Examples": [ + [ + "{{add 1 2}}", + "3" + ] + ] + }, + "Ceil": { + "Description": "Ceil returns the least integer value greater than or equal to num.", + "Args": [ + "num" + ], + "Aliases": null, + "Examples": [ + [ + "{{math.Ceil 2.1}}", + "3" + ] + ] + }, + "Counter": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Div": { + "Description": "Div divides num1 by num2.", + "Args": [ + "num1", + "num2" + ], + "Aliases": [ + "div" + ], + "Examples": [ + [ + "{{div 6 3}}", + "2" + ] + ] + }, + "Floor": { + "Description": "Floor returns the greatest integer value less than or equal to num.", + "Args": [ + "num" + ], + "Aliases": null, + "Examples": [ + [ + "{{math.Floor 1.9}}", + "1" + ] + ] + }, + "Log": { + "Description": "Log returns the natural logarithm of num.", + "Args": [ + "num" + ], + "Aliases": null, + "Examples": [ + [ + "{{math.Log 1}}", + "0" + ] + ] + }, + "Max": { + "Description": "Max returns the greater of num1 or num2.", + "Args": [ + "num1", + "num2" + ], + "Aliases": null, + "Examples": [ + [ + "{{math.Max 1 2 }}", + "2" + ] + ] + }, + "Min": { + "Description": "Min returns the smaller of two num1 or num2.", + "Args": [ + "num1", + "num2" + ], + "Aliases": null, + "Examples": [ + [ + "{{math.Min 1 2 }}", + "1" + ] + ] + }, + "Mod": { + "Description": "Mod returns num1 % num2.", + "Args": [ + "num1", + "num2" + ], + "Aliases": [ + "mod" + ], + "Examples": [ + [ + "{{mod 15 3}}", + "0" + ] + ] + }, + "ModBool": { + "Description": "ModBool returns the boolean of num1 % num2. If num1 % num2 == 0, return true.", + "Args": [ + "num1", + "num2" + ], + "Aliases": [ + "modBool" + ], + "Examples": [ + [ + "{{modBool 15 3}}", + "true" + ] + ] + }, + "Mul": { + "Description": "Mul multiplies num1 with num2.", + "Args": [ + "num1", + "num2" + ], + "Aliases": [ + "mul" + ], + "Examples": [ + [ + "{{mul 2 3}}", + "6" + ] + ] + }, + "Pow": { + "Description": "Pow returns num1 raised to the power of num2.", + "Args": [ + "num1", + "num2" + ], + "Aliases": [ + "pow" + ], + "Examples": [ + [ + "{{math.Pow 2 3}}", + "8" + ] + ] + }, + "Round": { + "Description": "Round returns the nearest integer of num, rounding half away from zero.", + "Args": [ + "num" + ], + "Aliases": null, + "Examples": [ + [ + "{{math.Round 1.5}}", + "2" + ] + ] + }, + "Sqrt": { + "Description": "Sqrt returns the square root of a num.", + "Args": [ + "num" + ], + "Aliases": null, + "Examples": [ + [ + "{{math.Sqrt 81}}", + "9" + ] + ] + }, + "Sub": { + "Description": "Sub subtracts num2 fron num1.", + "Args": [ + "num1", + "num2" + ], + "Aliases": [ + "sub" + ], + "Examples": [ + [ + "{{sub 3 2}}", + "1" + ] + ] + } + }, + "openapi3": { + "Unmarshal": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": [] + } + }, + "os": { + "FileExists": { + "Description": "FileExists checks whether a file exists under the given path.", + "Args": [ + "i" + ], + "Aliases": [ + "fileExists" + ], + "Examples": [ + [ + "{{ fileExists \"foo.txt\" }}", + "false" + ] + ] + }, + "Getenv": { + "Description": "Getenv retrieves the value of the environment variable named by the key.\nIt returns the value, which will be empty if the variable is not present.", + "Args": [ + "key" + ], + "Aliases": [ + "getenv" + ], + "Examples": [] + }, + "ReadDir": { + "Description": "ReadDir lists the directory contents relative to the configured WorkingDir.", + "Args": [ + "i" + ], + "Aliases": [ + "readDir" + ], + "Examples": [ + [ + "{{ range (readDir \"files\") }}{{ .Name }}{{ end }}", + "README.txt" + ] + ] + }, + "ReadFile": { + "Description": "ReadFile reads the file named by filename relative to the configured WorkingDir.\nIt returns the contents as a string.\nThere is an upper size limit set at 1 megabytes.", + "Args": [ + "i" + ], + "Aliases": [ + "readFile" + ], + "Examples": [ + [ + "{{ readFile \"files/README.txt\" }}", + "Hugo Rocks!" + ] + ] + }, + "Stat": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + } + }, + "partials": { + "Include": { + "Description": "Include executes the named partial.\nIf the partial contains a return statement, that value will be returned.\nElse, the rendered output will be returned:\nA string if the partial is a text/template, or template.HTML when html/template.\nNote that ctx is provided by Hugo, not the end user.", + "Args": [ + "ctx", + "name", + "contextList" + ], + "Aliases": [ + "partial" + ], + "Examples": [ + [ + "{{ partial \"header.html\" . }}", + "\u003ctitle\u003eHugo Rocks!\u003c/title\u003e" + ] + ] + }, + "IncludeCached": { + "Description": "IncludeCached executes and caches partial templates. The cache is created with name+variants as the key.\nNote that ctx is provided by Hugo, not the end user.", + "Args": [ + "ctx", + "name", + "context", + "variants" + ], + "Aliases": [ + "partialCached" + ], + "Examples": [] + } + }, + "path": { + "Base": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Clean": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Dir": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Ext": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Join": { + "Description": "Join joins any number of path elements into a single path, adding a\nseparating slash if necessary. All the input\npath elements are passed into filepath.ToSlash converting any Windows slashes\nto forward slashes.\nThe result is Cleaned; in particular,\nall empty strings are ignored.", + "Args": [ + "elements" + ], + "Aliases": null, + "Examples": [ + [ + "{{ slice \"my/path\" \"filename.txt\" | path.Join }}", + "my/path/filename.txt" + ], + [ + "{{ path.Join \"my\" \"path\" \"filename.txt\" }}", + "my/path/filename.txt" + ], + [ + "{{ \"my/path/filename.txt\" | path.Ext }}", + ".txt" + ], + [ + "{{ \"my/path/filename.txt\" | path.Base }}", + "filename.txt" + ], + [ + "{{ \"my/path/filename.txt\" | path.Dir }}", + "my/path" + ] + ] + }, + "Split": { + "Description": "Split splits path immediately following the final slash,\nseparating it into a directory and file name component.\nIf there is no slash in path, Split returns an empty dir and\nfile set to path.\nThe input path is passed into filepath.ToSlash converting any Windows slashes\nto forward slashes.\nThe returned values have the property that path = dir+file.", + "Args": [ + "path" + ], + "Aliases": null, + "Examples": [ + [ + "{{ \"/my/path/filename.txt\" | path.Split }}", + "/my/path/|filename.txt" + ], + [ + "{{ \"/my/path/filename.txt\" | path.Split }}", + "/my/path/|filename.txt" + ] + ] + } + }, + "reflect": { + "IsMap": { + "Description": "IsMap reports whether v is a map.", + "Args": [ + "v" + ], + "Aliases": null, + "Examples": [ + [ + "{{ if reflect.IsMap (dict \"a\" 1) }}Map{{ end }}", + "Map" + ] + ] + }, + "IsSlice": { + "Description": "IsSlice reports whether v is a slice.", + "Args": [ + "v" + ], + "Aliases": null, + "Examples": [ + [ + "{{ if reflect.IsSlice (slice 1 2 3) }}Slice{{ end }}", + "Slice" + ] + ] + } + }, + "resources": { + "Babel": { + "Description": "Babel processes the given Resource with Babel.", + "Args": [ + "args" + ], + "Aliases": [ + "babel" + ], + "Examples": [] + }, + "Concat": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "ExecuteAsTemplate": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Fingerprint": { + "Description": "Fingerprint transforms the given Resource with a MD5 hash of the content in\nthe RelPermalink and Permalink.", + "Args": [ + "args" + ], + "Aliases": [ + "fingerprint" + ], + "Examples": [] + }, + "FromString": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Get": { + "Description": "Get locates the filename given in Hugo's assets filesystem and\ncreates a Resource object that can be used for\nfurther transformations.", + "Args": [ + "filename" + ], + "Aliases": null, + "Examples": [] + }, + "GetMatch": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "GetRemote": { + "Description": "GetRemote gets the URL (via HTTP(s)) in the first argument in args and creates Resource object that can be used for\nfurther transformations.\n\nA second argument may be provided with an option map.\n\nNote: This method does not return any error as a second argument,\nfor any error situations the error can be checked in .Err.", + "Args": [ + "args" + ], + "Aliases": null, + "Examples": [] + }, + "Match": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Minify": { + "Description": "Minify minifies the given Resource using the MediaType to pick the correct\nminifier.", + "Args": [ + "r" + ], + "Aliases": [ + "minify" + ], + "Examples": [] + }, + "PostCSS": { + "Description": "PostCSS processes the given Resource with PostCSS", + "Args": [ + "args" + ], + "Aliases": [ + "postCSS" + ], + "Examples": [] + }, + "PostProcess": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "ToCSS": { + "Description": "ToCSS converts the given Resource to CSS. You can optional provide an Options\nobject or a target path (string) as first argument.", + "Args": [ + "args" + ], + "Aliases": [ + "toCSS" + ], + "Examples": [] + } + }, + "safe": { + "CSS": { + "Description": "CSS returns a given string as html/template CSS content.", + "Args": [ + "a" + ], + "Aliases": [ + "safeCSS" + ], + "Examples": [ + [ + "{{ \"Bat\u0026Man\" | safeCSS | safeCSS }}", + "Bat\u0026amp;Man" + ] + ] + }, + "HTML": { + "Description": "HTML returns a given string as html/template HTML content.", + "Args": [ + "a" + ], + "Aliases": [ + "safeHTML" + ], + "Examples": [ + [ + "{{ \"Bat\u0026Man\" | safeHTML | safeHTML }}", + "Bat\u0026Man" + ], + [ + "{{ \"Bat\u0026Man\" | safeHTML }}", + "Bat\u0026Man" + ] + ] + }, + "HTMLAttr": { + "Description": "HTMLAttr returns a given string as html/template HTMLAttr content.", + "Args": [ + "a" + ], + "Aliases": [ + "safeHTMLAttr" + ], + "Examples": [] + }, + "JS": { + "Description": "JS returns the given string as a html/template JS content.", + "Args": [ + "a" + ], + "Aliases": [ + "safeJS" + ], + "Examples": [ + [ + "{{ \"(1*2)\" | safeJS | safeJS }}", + "(1*2)" + ] + ] + }, + "JSStr": { + "Description": "JSStr returns the given string as a html/template JSStr content.", + "Args": [ + "a" + ], + "Aliases": [ + "safeJSStr" + ], + "Examples": [] + }, + "SanitizeURL": { + "Description": "SanitizeURL returns a given string as html/template URL content.", + "Args": [ + "a" + ], + "Aliases": [ + "sanitizeURL", + "sanitizeurl" + ], + "Examples": [] + }, + "URL": { + "Description": "URL returns a given string as html/template URL content.", + "Args": [ + "a" + ], + "Aliases": [ + "safeURL" + ], + "Examples": [ + [ + "{{ \"http://gohugo.io\" | safeURL | safeURL }}", + "http://gohugo.io" + ] + ] + } + }, + "site": { + "BaseURL": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Data": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Home": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Hugo": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "IsServer": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Language": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "LastChange": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Menus": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Pages": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Params": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "RegularPages": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "ServerPort": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Sites": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Taxonomies": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Title": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + } + }, + "strings": { + "Chomp": { + "Description": "Chomp returns a copy of s with all trailing newline characters removed.", + "Args": [ + "s" + ], + "Aliases": [ + "chomp" + ], + "Examples": [ + [ + "{{chomp \"\u003cp\u003eBlockhead\u003c/p\u003e\\n\" | safeHTML }}", + "\u003cp\u003eBlockhead\u003c/p\u003e" + ] + ] + }, + "Contains": { + "Description": "Contains reports whether substr is in s.", + "Args": [ + "s", + "substr" + ], + "Aliases": null, + "Examples": [ + [ + "{{ strings.Contains \"abc\" \"b\" }}", + "true" + ], + [ + "{{ strings.Contains \"abc\" \"d\" }}", + "false" + ] + ] + }, + "ContainsAny": { + "Description": "ContainsAny reports whether any Unicode code points in chars are within s.", + "Args": [ + "s", + "chars" + ], + "Aliases": null, + "Examples": [ + [ + "{{ strings.ContainsAny \"abc\" \"bcd\" }}", + "true" + ], + [ + "{{ strings.ContainsAny \"abc\" \"def\" }}", + "false" + ] + ] + }, + "Count": { + "Description": "Count counts the number of non-overlapping instances of substr in s.\nIf substr is an empty string, Count returns 1 + the number of Unicode code points in s.", + "Args": [ + "substr", + "s" + ], + "Aliases": null, + "Examples": [ + [ + "{{\"aabab\" | strings.Count \"a\" }}", + "3" + ] + ] + }, + "CountRunes": { + "Description": "CountRunes returns the number of runes in s, excluding whitespace.", + "Args": [ + "s" + ], + "Aliases": [ + "countrunes" + ], + "Examples": [] + }, + "CountWords": { + "Description": "CountWords returns the approximate word count in s.", + "Args": [ + "s" + ], + "Aliases": [ + "countwords" + ], + "Examples": [] + }, + "FindRE": { + "Description": "FindRE returns a list of strings that match the regular expression. By default all matches\nwill be included. The number of matches can be limited with an optional third parameter.", + "Args": [ + "expr", + "content", + "limit" + ], + "Aliases": [ + "findRE" + ], + "Examples": [ + [ + "{{ findRE \"[G|g]o\" \"Hugo is a static side generator written in Go.\" \"1\" }}", + "[go]" + ] + ] + }, + "FirstUpper": { + "Description": "FirstUpper returns a string with the first character as upper case.", + "Args": [ + "s" + ], + "Aliases": null, + "Examples": [ + [ + "{{ \"hugo rocks!\" | strings.FirstUpper }}", + "Hugo rocks!" + ] + ] + }, + "HasPrefix": { + "Description": "HasPrefix tests whether the input s begins with prefix.", + "Args": [ + "s", + "prefix" + ], + "Aliases": [ + "hasPrefix" + ], + "Examples": [ + [ + "{{ hasPrefix \"Hugo\" \"Hu\" }}", + "true" + ], + [ + "{{ hasPrefix \"Hugo\" \"Fu\" }}", + "false" + ] + ] + }, + "HasSuffix": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Repeat": { + "Description": "Repeat returns a new string consisting of count copies of the string s.", + "Args": [ + "n", + "s" + ], + "Aliases": null, + "Examples": [ + [ + "{{ \"yo\" | strings.Repeat 4 }}", + "yoyoyoyo" + ] + ] + }, + "Replace": { + "Description": "Replace returns a copy of the string s with all occurrences of old replaced\nwith new. The number of replacements can be limited with an optional fourth\nparameter.", + "Args": [ + "s", + "old", + "new", + "limit" + ], + "Aliases": [ + "replace" + ], + "Examples": [ + [ + "{{ replace \"Batman and Robin\" \"Robin\" \"Catwoman\" }}", + "Batman and Catwoman" + ], + [ + "{{ replace \"aabbaabb\" \"a\" \"z\" 2 }}", + "zzbbaabb" + ] + ] + }, + "ReplaceRE": { + "Description": "ReplaceRE returns a copy of s, replacing all matches of the regular\nexpression pattern with the replacement text repl. The number of replacements\ncan be limited with an optional fourth parameter.", + "Args": [ + "pattern", + "repl", + "s", + "n" + ], + "Aliases": [ + "replaceRE" + ], + "Examples": [ + [ + "{{ replaceRE \"a+b\" \"X\" \"aabbaabbab\" }}", + "XbXbX" + ], + [ + "{{ replaceRE \"a+b\" \"X\" \"aabbaabbab\" 1 }}", + "Xbaabbab" + ] + ] + }, + "RuneCount": { + "Description": "RuneCount returns the number of runes in s.", + "Args": [ + "s" + ], + "Aliases": null, + "Examples": [] + }, + "SliceString": { + "Description": "SliceString slices a string by specifying a half-open range with\ntwo indices, start and end. 1 and 4 creates a slice including elements 1 through 3.\nThe end index can be omitted, it defaults to the string's length.", + "Args": [ + "a", + "startEnd" + ], + "Aliases": [ + "slicestr" + ], + "Examples": [ + [ + "{{slicestr \"BatMan\" 0 3}}", + "Bat" + ], + [ + "{{slicestr \"BatMan\" 3}}", + "Man" + ] + ] + }, + "Split": { + "Description": "Split slices an input string into all substrings separated by delimiter.", + "Args": [ + "a", + "delimiter" + ], + "Aliases": [ + "split" + ], + "Examples": [] + }, + "Substr": { + "Description": "Substr extracts parts of a string, beginning at the character at the specified\nposition, and returns the specified number of characters.\n\nIt normally takes two parameters: start and length.\nIt can also take one parameter: start, i.e. length is omitted, in which case\nthe substring starting from start until the end of the string will be returned.\n\nTo extract characters from the end of the string, use a negative start number.\n\nIn addition, borrowing from the extended behavior described at http://php.net/substr,\nif length is given and is negative, then that many characters will be omitted from\nthe end of string.", + "Args": [ + "a", + "nums" + ], + "Aliases": [ + "substr" + ], + "Examples": [ + [ + "{{substr \"BatMan\" 0 -3}}", + "Bat" + ], + [ + "{{substr \"BatMan\" 3 3}}", + "Man" + ] + ] + }, + "Title": { + "Description": "Title returns a copy of the input s with all Unicode letters that begin words\nmapped to their title case.", + "Args": [ + "s" + ], + "Aliases": [ + "title" + ], + "Examples": [ + [ + "{{title \"Bat man\"}}", + "Bat Man" + ], + [ + "{{title \"somewhere over the rainbow\"}}", + "Somewhere Over the Rainbow" + ] + ] + }, + "ToLower": { + "Description": "ToLower returns a copy of the input s with all Unicode letters mapped to their\nlower case.", + "Args": [ + "s" + ], + "Aliases": [ + "lower" + ], + "Examples": [ + [ + "{{lower \"BatMan\"}}", + "batman" + ] + ] + }, + "ToUpper": { + "Description": "ToUpper returns a copy of the input s with all Unicode letters mapped to their\nupper case.", + "Args": [ + "s" + ], + "Aliases": [ + "upper" + ], + "Examples": [ + [ + "{{upper \"BatMan\"}}", + "BATMAN" + ] + ] + }, + "Trim": { + "Description": "Trim returns a string with all leading and trailing characters defined\ncontained in cutset removed.", + "Args": [ + "s", + "cutset" + ], + "Aliases": [ + "trim" + ], + "Examples": [ + [ + "{{ trim \"++Batman--\" \"+-\" }}", + "Batman" + ] + ] + }, + "TrimLeft": { + "Description": "TrimLeft returns a slice of the string s with all leading characters\ncontained in cutset removed.", + "Args": [ + "cutset", + "s" + ], + "Aliases": null, + "Examples": [ + [ + "{{ \"aabbaa\" | strings.TrimLeft \"a\" }}", + "bbaa" + ] + ] + }, + "TrimPrefix": { + "Description": "TrimPrefix returns s without the provided leading prefix string. If s doesn't\nstart with prefix, s is returned unchanged.", + "Args": [ + "prefix", + "s" + ], + "Aliases": null, + "Examples": [ + [ + "{{ \"aabbaa\" | strings.TrimPrefix \"a\" }}", + "abbaa" + ], + [ + "{{ \"aabbaa\" | strings.TrimPrefix \"aa\" }}", + "bbaa" + ] + ] + }, + "TrimRight": { + "Description": "TrimRight returns a slice of the string s with all trailing characters\ncontained in cutset removed.", + "Args": [ + "cutset", + "s" + ], + "Aliases": null, + "Examples": [ + [ + "{{ \"aabbaa\" | strings.TrimRight \"a\" }}", + "aabb" + ] + ] + }, + "TrimSuffix": { + "Description": "TrimSuffix returns s without the provided trailing suffix string. If s\ndoesn't end with suffix, s is returned unchanged.", + "Args": [ + "suffix", + "s" + ], + "Aliases": null, + "Examples": [ + [ + "{{ \"aabbaa\" | strings.TrimSuffix \"a\" }}", + "aabba" + ], + [ + "{{ \"aabbaa\" | strings.TrimSuffix \"aa\" }}", + "aabb" + ] + ] + }, + "Truncate": { + "Description": "Truncate truncates a given string to the specified length.", + "Args": [ + "a", + "options" + ], + "Aliases": [ + "truncate" + ], + "Examples": [ + [ + "{{ \"this is a very long text\" | truncate 10 \" ...\" }}", + "this is a ..." + ], + [ + "{{ \"With [Markdown](/markdown) inside.\" | markdownify | truncate 14 }}", + "With \u003ca href=\"/markdown\"\u003eMarkdown …\u003c/a\u003e" + ] + ] + } + }, + "templates": { + "Exists": { + "Description": "Exists returns whether the template with the given name exists.\nNote that this is the Unix-styled relative path including filename suffix,\ne.g. partials/header.html", + "Args": [ + "name" + ], + "Aliases": null, + "Examples": [ + [ + "{{ if (templates.Exists \"partials/header.html\") }}Yes!{{ end }}", + "Yes!" + ], + [ + "{{ if not (templates.Exists \"partials/doesnotexist.html\") }}No!{{ end }}", + "No!" + ] + ] + } + }, + "time": { + "AsTime": { + "Description": "AsTime converts the textual representation of the datetime string into\na time.Time interface.", + "Args": [ + "v", + "args" + ], + "Aliases": null, + "Examples": [ + [ + "{{ (time \"2015-01-21\").Year }}", + "2015" + ] + ] + }, + "Duration": { + "Description": "Duration converts the given number to a time.Duration.\nUnit is one of nanosecond/ns, microsecond/us/µs, millisecond/ms, second/s, minute/m or hour/h.", + "Args": [ + "unit", + "number" + ], + "Aliases": [ + "duration" + ], + "Examples": [ + [ + "{{ mul 60 60 | duration \"second\" }}", + "1h0m0s" + ] + ] + }, + "Format": { + "Description": "Format converts the textual representation of the datetime string into\nthe other form or returns it of the time.Time value. These are formatted\nwith the layout string", + "Args": [ + "layout", + "v" + ], + "Aliases": [ + "dateFormat" + ], + "Examples": [ + [ + "dateFormat: {{ dateFormat \"Monday, Jan 2, 2006\" \"2015-01-21\" }}", + "dateFormat: Wednesday, Jan 21, 2015" + ] + ] + }, + "Now": { + "Description": "Now returns the current local time.", + "Args": null, + "Aliases": [ + "now" + ], + "Examples": [] + }, + "ParseDuration": { + "Description": "ParseDuration parses a duration string.\nA duration string is a possibly signed sequence of\ndecimal numbers, each with optional fraction and a unit suffix,\nsuch as \"300ms\", \"-1.5h\" or \"2h45m\".\nValid time units are \"ns\", \"us\" (or \"µs\"), \"ms\", \"s\", \"m\", \"h\".\nSee https://golang.org/pkg/time/#ParseDuration", + "Args": [ + "in" + ], + "Aliases": null, + "Examples": [ + [ + "{{ \"1h12m10s\" | time.ParseDuration }}", + "1h12m10s" + ] + ] + } + }, + "transform": { + "CanHighlight": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Emojify": { + "Description": "Emojify returns a copy of s with all emoji codes replaced with actual emojis.\n\nSee http://www.emoji-cheat-sheet.com/", + "Args": [ + "s" + ], + "Aliases": [ + "emojify" + ], + "Examples": [ + [ + "{{ \"I :heart: Hugo\" | emojify }}", + "I ❤️ Hugo" + ] + ] + }, + "HTMLEscape": { + "Description": "HTMLEscape returns a copy of s with reserved HTML characters escaped.", + "Args": [ + "s" + ], + "Aliases": [ + "htmlEscape" + ], + "Examples": [ + [ + "{{ htmlEscape \"Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e\" | safeHTML}}", + "Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;" + ], + [ + "{{ htmlEscape \"Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e\"}}", + "Cathal Garvey \u0026amp;amp; The Sunshine Band \u0026amp;lt;cathal@foo.bar\u0026amp;gt;" + ], + [ + "{{ htmlEscape \"Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e\" | htmlUnescape | safeHTML }}", + "Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e" + ] + ] + }, + "HTMLUnescape": { + "Description": "HTMLUnescape returns a copy of with HTML escape requences converted to plain\ntext.", + "Args": [ + "s" + ], + "Aliases": [ + "htmlUnescape" + ], + "Examples": [ + [ + "{{ htmlUnescape \"Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;\" | safeHTML}}", + "Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e" + ], + [ + "{{\"Cathal Garvey \u0026amp;amp; The Sunshine Band \u0026amp;lt;cathal@foo.bar\u0026amp;gt;\" | htmlUnescape | htmlUnescape | safeHTML}}", + "Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e" + ], + [ + "{{\"Cathal Garvey \u0026amp;amp; The Sunshine Band \u0026amp;lt;cathal@foo.bar\u0026amp;gt;\" | htmlUnescape | htmlUnescape }}", + "Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;" + ], + [ + "{{ htmlUnescape \"Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;\" | htmlEscape | safeHTML }}", + "Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;" + ] + ] + }, + "Highlight": { + "Description": "Highlight returns a copy of s as an HTML string with syntax\nhighlighting applied.", + "Args": [ + "s", + "lang", + "opts" + ], + "Aliases": [ + "highlight" + ], + "Examples": [] + }, + "HighlightCodeBlock": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Markdownify": { + "Description": "Markdownify renders a given input from Markdown to HTML.", + "Args": [ + "s" + ], + "Aliases": [ + "markdownify" + ], + "Examples": [ + [ + "{{ .Title | markdownify}}", + "\u003cstrong\u003eBatMan\u003c/strong\u003e" + ] + ] + }, + "Plainify": { + "Description": "Plainify returns a copy of s with all HTML tags removed.", + "Args": [ + "s" + ], + "Aliases": [ + "plainify" + ], + "Examples": [ + [ + "{{ plainify \"Hello \u003cstrong\u003eworld\u003c/strong\u003e, gophers!\" }}", + "Hello world, gophers!" + ] + ] + }, + "Remarshal": { + "Description": "Remarshal is used in the Hugo documentation to convert configuration\nexamples from YAML to JSON, TOML (and possibly the other way around).\nThe is primarily a helper for the Hugo docs site.\nIt is not a general purpose YAML to TOML converter etc., and may\nchange without notice if it serves a purpose in the docs.\nFormat is one of json, yaml or toml.", + "Args": [ + "format", + "data" + ], + "Aliases": null, + "Examples": [ + [ + "{{ \"title = \\\"Hello World\\\"\" | transform.Remarshal \"json\" | safeHTML }}", + "{\n \"title\": \"Hello World\"\n}\n" + ] + ] + }, + "Unmarshal": { + "Description": "Unmarshal unmarshals the data given, which can be either a string, json.RawMessage\nor a Resource. Supported formats are JSON, TOML, YAML, and CSV.\nYou can optionally provide an options map as the first argument.", + "Args": [ + "args" + ], + "Aliases": [ + "unmarshal" + ], + "Examples": [ + [ + "{{ \"hello = \\\"Hello World\\\"\" | transform.Unmarshal }}", + "map[hello:Hello World]" + ], + [ + "{{ \"hello = \\\"Hello World\\\"\" | resources.FromString \"data/greetings.toml\" | transform.Unmarshal }}", + "map[hello:Hello World]" + ] + ] + } + }, + "urls": { + "AbsLangURL": { + "Description": "AbsLangURL takes a given string and converts it to an absolute URL according\nto a page's position in the project directory structure and the current\nlanguage.", + "Args": [ + "a" + ], + "Aliases": [ + "absLangURL" + ], + "Examples": [] + }, + "AbsURL": { + "Description": "AbsURL takes a given string and converts it to an absolute URL.", + "Args": [ + "a" + ], + "Aliases": [ + "absURL" + ], + "Examples": [] + }, + "Anchorize": { + "Description": "Anchorize creates sanitized anchor names that are compatible with Blackfriday.", + "Args": [ + "a" + ], + "Aliases": [ + "anchorize" + ], + "Examples": [ + [ + "{{ \"This is a title\" | anchorize }}", + "this-is-a-title" + ] + ] + }, + "Parse": { + "Description": "", + "Args": null, + "Aliases": null, + "Examples": null + }, + "Ref": { + "Description": "Ref returns the absolute URL path to a given content item.", + "Args": [ + "in", + "args" + ], + "Aliases": [ + "ref" + ], + "Examples": [] + }, + "RelLangURL": { + "Description": "RelLangURL takes a given string and prepends the relative path according to a\npage's position in the project directory structure and the current language.", + "Args": [ + "a" + ], + "Aliases": [ + "relLangURL" + ], + "Examples": [] + }, + "RelRef": { + "Description": "RelRef returns the relative URL path to a given content item.", + "Args": [ + "in", + "args" + ], + "Aliases": [ + "relref" + ], + "Examples": [] + }, + "RelURL": { + "Description": "RelURL takes a given string and prepends the relative path according to a\npage's position in the project directory structure.", + "Args": [ + "a" + ], + "Aliases": [ + "relURL" + ], + "Examples": [] + }, + "URLize": { + "Description": "URLize returns the given argument formatted as URL.", + "Args": [ + "a" + ], + "Aliases": [ + "urlize" + ], + "Examples": [] + } + } + } + } +} diff --git a/exampleSite/archetypes/namespace/index.md b/exampleSite/archetypes/namespace/index.md new file mode 100644 index 0000000..a0a33a0 --- /dev/null +++ b/exampleSite/archetypes/namespace/index.md @@ -0,0 +1,7 @@ +--- +title: "{{ .Name | title }} Namespace" +linkTitle: "{{ .Name | title }}" +namespace: "{{ .Name }}" +--- + + diff --git a/exampleSite/config.toml b/exampleSite/config.toml index ac3f825..17e4c81 100644 --- a/exampleSite/config.toml +++ b/exampleSite/config.toml @@ -23,23 +23,21 @@ disableAliases = true [build] # Used by PurgeCSS writeStats = true +useResourceCacheWhen = 'never' [params] ghrepo = "https://github.com/gohugoio/hugoDocs/" - -# Make the categories listing share the layouts from documentation. +# Make the categories and tags listings share the layouts from documentation. [[cascade]] type = 'documentation' [cascade._target] path = '/categories/**' - -[markup] -[markup.highlight] -style = "trac" -lineNumbersInTable = true -noClasses = false +[[cascade]] +type = 'documentation' +[cascade._target] +path = '/tags/**' [minify] @@ -48,8 +46,11 @@ noClasses = false [minify.tdewolff.html] keepWhitespace = true - [module] +[[module.mounts]] +lang = "en" +source = "content/en" +target = "content" [[module.imports]] path = "github.com/gohugoio/gohugoioTheme2" [[module.imports]] @@ -59,20 +60,10 @@ ignoreConfig = true ignoreImports = true [[module.imports.mounts]] lang = "en" -source = "content/en" -target = "content/documentation" - -[[module.imports.mounts]] -lang = "en" source = "content/site/en" target = "content" [[module.imports.mounts]] -lang = "zh" -source = "content/zh" -target = "content/documentation" - -[[module.imports.mounts]] source = "static" target = "static" @@ -97,7 +88,7 @@ source = "archetypes" target = "archetypes" [outputs] -home = [ "HTML", "RSS", "REDIR", "HEADERS" ] +home = [ "HTML", "RSS", "REDIR", "HEADERS", "DOCTREE" ] section = [ "HTML", "RSS"] [mediaTypes] @@ -115,6 +106,11 @@ mediatype = "text/netlify" baseName = "_headers" isPlainText = true notAlternative = true +[outputFormats.DOCTREE] +mediatype = "application/json" +baseName = "doctree" +isPlainText = true +notAlternative = true ## Relatd configuration. @@ -126,6 +122,9 @@ toLower = false [[related.indices]] name = "keywords" +weight = 80 +[[related.indices]] +name = "tags" weight = 100 [[related.indices]] name = "date" @@ -155,4 +154,4 @@ resampleFilter = "CatmullRom" # Default JPEG quality setting. Default is 75. quality = 75 -anchor = "smart"
\ No newline at end of file +anchor = "smart" diff --git a/exampleSite/config/_default/markup.toml b/exampleSite/config/_default/markup.toml new file mode 100644 index 0000000..ce50aee --- /dev/null +++ b/exampleSite/config/_default/markup.toml @@ -0,0 +1,32 @@ +defaultMarkdownHandler = "goldmark" + +[goldmark] +[goldmark.extensions] +definitionList = true +footnote = true +linkify = true +strikethrough = true +table = true +taskList = true +typographer = true + +[goldmark.parser] +autoHeadingID = true +autoHeadingIDType = "github" +[goldmark.parser.attribute] +block = true +title = true +[goldmark.renderer] +hardWraps = false +unsafe = true +xhtml = false + +[highlight] +style = "trac" +lineNumbersInTable = true +noClasses = false + +[tableOfContents] +endLevel = 2 +ordered = false +startLevel = 2 diff --git a/exampleSite/content/en/documentation/_index.md b/exampleSite/content/en/documentation/_index.md new file mode 100644 index 0000000..c93808a --- /dev/null +++ b/exampleSite/content/en/documentation/_index.md @@ -0,0 +1,8 @@ +--- +title: Hugo Documentation +linkTitle: Docs +cascade: + weight: 501 + +--- + diff --git a/exampleSite/content/en/documentation/explanation/_index.md b/exampleSite/content/en/documentation/explanation/_index.md new file mode 100644 index 0000000..34dcd32 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/_index.md @@ -0,0 +1,5 @@ +--- +title: "Explanation" +linkTitle: "Explanation" +weight: 20 +--- diff --git a/exampleSite/content/en/documentation/explanation/content-management/_index.md b/exampleSite/content/en/documentation/explanation/content-management/_index.md new file mode 100644 index 0000000..1343998 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/_index.md @@ -0,0 +1,11 @@ +--- +title: Content Management +linktitle: Content +description: Hugo makes managing large static sites easy with support for archetypes, content types, +weight: 01 #rem +draft: false +aliases: [/content/,/content/organization] +toc: false +--- + +A static site generator needs to extend beyond front matter and a couple of templates to be both scalable and *manageable*. Hugo was designed with not only developers in mind, but also content managers and authors. diff --git a/exampleSite/content/en/documentation/explanation/content-management/archetypes.md b/exampleSite/content/en/documentation/explanation/content-management/archetypes.md new file mode 100644 index 0000000..9f572e6 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/archetypes.md @@ -0,0 +1,93 @@ +--- +title: Archetypes +linktitle: Archetypes +description: Archetypes are templates used when creating new content. +date: 2017-02-01 +publishdate: 2017-02-01 +keywords: [archetypes,generators,metadata,front matter] +categories: ["content management"] + +weight: 70 #rem +draft: false +aliases: [/content/archetypes/] +toc: true +--- + +## What are Archetypes? + +**Archetypes** are content template files in the [archetypes directory][] of your project that contain preconfigured [front matter][] and possibly also a content disposition for your website's [content types][]. These will be used when you run `hugo new`. + + +The `hugo new` uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetype files, it will also look in the theme. + +{{< code file="archetype-example.sh" >}} +hugo new posts/my-first-post.md +{{< /code >}} + +The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these: + +1. `archetypes/posts.md` +2. `archetypes/default.md` +3. `themes/my-theme/archetypes/posts.md` +4. `themes/my-theme/archetypes/default.md` + +The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example. + +## Create a New Archetype Template + +A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`. Create a new file in `archetypes/newsletter.md` and open it in a text editor. + +{{< code file="archetypes/newsletter.md" >}} +--- +title: "{{ replace .Name "-" " " | title }}" +date: {{ .Date }} +draft: true +--- + +**Insert Lead paragraph here.** + +## New Cool Posts + +{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }} +* {{ .Title }} +{{ end }} +{{< /code >}} + +When you create a new newsletter with: + +```bash +hugo new newsletter/the-latest-cool.stuff.md +``` + +It will create a new newsletter type of content file based on the archetype template. + +**Note:** the site will only be built if the `.Site` is in use in the archetype file, and this can be time consuming for big sites. + +The above _newsletter type archetype_ illustrates the possibilities: The full Hugo `.Site` and all of Hugo's template funcs can be used in the archetype file. + + +## Directory based archetypes + +Since Hugo `0.49` you can use complete directories as archetype templates. Given this archetype directory: + +```bash +archetypes +├── default.md +└── post-bundle + ├── bio.md + ├── images + │ └── featured.jpg + └── index.md +``` + +```bash +hugo new --kind post-bundle posts/my-post +``` + +Will create a new folder in `/content/posts/my-post` with the same set of files as in the `post-bundle` archetypes folder. All content files (`index.md` etc.) can contain template logic, and will receive the correct `.Site` for the content's language. + + + +[archetypes directory]: /getting-started/directory-structure/ +[content types]: /content-management/types/ +[front matter]: /content-management/front-matter/ diff --git a/exampleSite/content/en/documentation/explanation/content-management/authors.md b/exampleSite/content/en/documentation/explanation/content-management/authors.md new file mode 100644 index 0000000..4a00fae --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/authors.md @@ -0,0 +1,178 @@ +--- +title: Authors +linktitle: Authors +description: +date: 2016-08-22 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +keywords: [authors] +categories: ["content management"] +weight: 55 #rem +draft: true +aliases: [/content/archetypes/] +toc: true +comments: Before this page is published, need to also update both site- and page-level variables documentation. +--- + +Larger sites often have multiple content authors. Hugo provides standardized author profiles to organize relationships between content and content creators for sites operating under a distributed authorship model. + +## Author Profiles + +You can create a profile containing metadata for each author on your website. These profiles have to be saved under `data/_authors/`. The filename of the profile will later be used as an identifier. This way Hugo can associate content with one or multiple authors. An author's profile can be defined in the JSON, YAML, or TOML format. + +### Example: Author Profile + +Let's suppose Alice Allison is a blogger. A simple unique identifier would be `alice`. Now, we have to create a file called `alice.toml` in the `data/_authors/` directory. The following example is the standardized template written in TOML: + +{{< code file="data/_authors/alice.toml" >}} +givenName = "Alice" # or firstName as alias +familyName = "Allison" # or lastName as alias +displayName = "Alice Allison" +thumbnail = "static/authors/alice-thumb.jpg" +image = "static/authors/alice-full.jpg" +shortBio = "My name is Alice and I'm a blogger." +bio = "My name is Alice and I'm a blogger... some other stuff" +email = "alice.allison@email.com" +weight = 10 + +[social] + facebook = "alice.allison" + twitter = "alice" + website = "www.example.com" + +[params] + random = "whatever you want" +{{< /code >}} + +All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage. + +You can store files for the `thumbnail` and `image` attributes in the `static` folder. Then add the path to the photos relative to `static`; e.g., `/static/path/to/thumbnail.jpg`. + +`weight` allows you to define the order of an author in an `.Authors` list and can be accessed on list or via the `.Site.Authors` variable. + +The `social` section contains all the links to the social network accounts of an author. Hugo is able to generate the account links for the most popular social networks automatically. This way, you only have to enter your username. You can find a list of all supported social networks [here](#linking-social-network-accounts-automatically). All other variables, like `website` in the example above remain untouched. + +The `params` section can contain arbitrary data much like the same-named section in the config file. What it contains is up to you. + +## Associate Content Through Identifiers + +Earlier it was mentioned that content can be associated with an author through their corresponding identifier. In our case, blogger Alice has the identifier `alice`. In the front matter of a content file, you can create a list of identifiers and assign it to the `authors` variable. Here are examples for `alice` using YAML and TOML, respectively. + +``` +--- +title: Why Hugo is so Awesome +date: 2016-08-22T14:27:502:00 +authors: ["alice"] +--- + +Nothing to read here. Move along... +``` + +``` ++++ +title = Why Hugo is so Awesome +date = "2016-08-22T14:27:502:00" +authors: ["alice"] ++++ + +Nothing to read here. Move along... +``` + +Future authors who might work on this blog post can append their identifiers to the `authors` array in the front matter as well. + +## Work with Templates + +After a successful setup it's time to give some credit to the authors by showing them on the website. Within the templates Hugo provides a list of the author's profiles if they are listed in the `authors` variable within the front matter. + +The list is accessible via the `.Authors` template variable. Printing all authors of a the blog post is straight forward: + +``` +{{ range .Authors }} + {{ .DisplayName }} +{{ end }} +=> Alice Allison +``` + +Even if there are co-authors you may only want to show the main author. For this case you can use the `.Author` template variable **(note the singular form)**. The template variable contains the profile of the author that is first listed with his identifier in the front matter. + +{{% note %}} +You can find a list of all template variables to access the profile information in [Author Variables](/variables/authors/). +{{% /note %}} + +### Link Social Network Accounts + +As aforementioned, Hugo is able to generate links to profiles of the most popular social networks. The following social networks with their corresponding identifiers are supported: `github`, `facebook`, `twitter`, `pinterest`, `instagram`, `youtube` and `linkedin`. + +This is can be done with the `.Social.URL` function. Its only parameter is the name of the social network as they are defined in the profile (e.g. `facebook`, `twitter`). Custom variables like `website` remain as they are. + +Most articles feature a small section with information about the author at the end. Let's create one containing the author's name, a thumbnail, a (summarized) biography and links to all social networks: + +{{< code file="layouts/partials/author-info.html" download="author-info.html" >}} +{{ with .Author }} + <h3>{{ .DisplayName }}</h3> + <img src="{{ .Thumbnail | absURL }}" alt="{{ .DisplayName }}"> + <p>{{ .ShortBio }}</p> + <ul> + {{ range $network, $username := .Social }} + <li><a href="{{ $.Author.Social.URL $network }}">{{ $network }}</a></li> + {{ end }} + </ul> +{{ end }} +{{< /code >}} + +## Who Published What? + +That question can be answered with a list of all authors and another list containing all articles that they each have written. Now we have to translate this idea into templates. The [taxonomy][] feature allows us to logically group content based on information that they have in common; e.g. a tag or a category. Well, many articles share the same author, so this should sound familiar, right? + +In order to let Hugo know that we want to group content based on their author, we have to create a new taxonomy called `author` (the name corresponds to the variable in the front matter). Here is the snippet in a `config.yaml` and `config.toml`, respectively: + +``` +taxonomies: + author: authors +``` + +``` +[taxonomies] + author = "authors" +``` + + +### List All Authors + +In the next step we can create a template to list all authors of your website. Later, the list can be accessed at `www.example.com/authors/`. Create a new template in the `layouts/taxonomy/` directory called `authors.term.html`. This template will be exclusively used for this taxonomy. + +{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}} +<ul> +{{ range $author, $v := .Data.Terms }} + {{ $profile := $.Authors.Get $author }} + <li> + <a href="{{ printf "%s/%s/" $.Data.Plural $author | absURL }}"> + {{ $profile.DisplayName }} - {{ $profile.ShortBio }} + </a> + </li> +{{ end }} +</ul> +{{< /code >}} + +`.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically). + +### List Each Author's Publications + +Last but not least, we have to create the second list that contains all publications of an author. Each list will be shown in its own page and can be accessed at `www.example.com/authors/<IDENTIFIER>`. Replace `<IDENTIFIER>` with a valid author identifier like `alice`. + +The layout for this page can be defined in the template `layouts/taxonomy/author.html`. + +{{< code file="layouts/taxonomy/author.html" download="author.html" >}} +{{ range .Pages }} + <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2> + <span>written by {{ .Author.DisplayName }}</span> + {{ .Summary }} +{{ end }} +{{< /code >}} + +The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags. + +With a lot of content this list can quickly become very long. Consider to use the [pagination][] feature. It splits the list into smaller chunks and spreads them over multiple pages. + +[pagevars]: /variables/page/ +[pagination]: /templates/pagination/ diff --git a/exampleSite/content/en/documentation/explanation/content-management/build-options.md b/exampleSite/content/en/documentation/explanation/content-management/build-options.md new file mode 100644 index 0000000..775067a --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/build-options.md @@ -0,0 +1,116 @@ +--- +title: Build Options +linktitle: Build Options +description: Build options help define how Hugo must treat a given page when building the site. +date: 2020-03-02 +publishdate: 2020-03-02 +keywords: [build,content,front matter, page resources] +categories: ["content management"] + +weight: 31 #rem +draft: false +aliases: [/content/build-options/] +toc: true +--- + +They are stored in a reserved Front Matter object named `_build` with the following defaults: + +```yaml +_build: + render: always + list: always + publishResources: true +``` + +#### render +If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink. + +{{< new-in "0.76.0" >}} We extended this property from a boolean to an enum in Hugo 0.76.0. Valid values are: + +never +: The page will not be included in any page collection. + +always (default) +: The page will be rendered to disk and get a `RelPermalink` etc. + +link +: The page will be not be rendered to disk, but will get a `RelPermalink`. + +#### list + +Note that we extended this property from a boolean to an enum in Hugo 0.68.0. + +Valid values are: + +never +: The page will not be included in any page collection. + +always (default) +: The page will be included in all page collections, e.g. `site.RegularPages`, `$page.Pages`. + +local +: The page will be included in any _local_ page collection, e.g. `$page.RegularPages`, `$page.Pages`. One use case for this would be to create fully navigable, but headless content sections. {{< new-in "0.68.0" >}} + +If true, the page will be treated as part of the project's collections and, when appropriate, returned by Hugo's listing methods (`.Pages`, `.RegularPages` etc...). + +#### publishResources + +If set to true the [Bundle's Resources]({{< relref "content-management/page-bundles" >}}) will be published. +Setting this to false will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others. + +{{% note %}} +Any page, regardless of their build options, will always be available using the [`.GetPage`]({{< relref "functions/GetPage" >}}) methods. +{{% /note %}} + +------ + +### Illustrative use cases + +#### Not publishing a page +Project needs a "Who We Are" content file for Front Matter and body to be used by the homepage but nowhere else. + +```yaml +# content/who-we-are.md` +title: Who we are +_build: + list: false + render: false +``` + +```go-html-template +{{/* layouts/index.html */}} +<section id="who-we-are"> +{{ with site.GetPage "who-we-are" }} + {{ .Content }} +{{ end }} +</section> +``` + +#### Listing pages without publishing them + +Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them. + +To avoid setting the build options on every testimonials, one can use [`cascade`]({{< relref "/content-management/front-matter#front-matter-cascade" >}}) on the testimonial section's content file. + +```yaml +#content/testimonials/_index.md +title: Testimonials +# section build options: +_build: + render: true +# children build options with cascade +cascade: + _build: + render: false + list: true # default +``` + +```go-html-template +{{/* layouts/_defaults/testimonials.html */}} +<section id="testimonials"> +{{ range first 5 .Pages }} + <blockquote cite="{{ .Params.cite }}"> + {{ .Content }} + </blockquote> +{{ end }} +</section> diff --git a/exampleSite/content/en/documentation/explanation/content-management/comments.md b/exampleSite/content/en/documentation/explanation/content-management/comments.md new file mode 100644 index 0000000..d693123 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/comments.md @@ -0,0 +1,74 @@ +--- +title: Comments +linktitle: Comments +description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-09 +keywords: [sections,content,organization] +categories: [project organization, fundamentals] + +weight: 140 #rem +draft: false +aliases: [/extras/comments/] +toc: true +--- + +Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript. + +Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial]. + +## Add Disqus + +Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup]. + +### Configure Disqus + +Disqus comments require you set a single value in your [site's configuration file][configuration] like so: + +{{< code-toggle copy="false" >}} +disqusShortname = "yourdiscussshortname" +{{</ code-toggle >}} + +For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file: + +* `disqus_identifier` +* `disqus_title` +* `disqus_url` + +### Render Hugo's Built-in Disqus Partial Template + +Disqus has its own [internal template](https://gohugo.io/templates/internal/#disqus) available, to render it add the following code where you want comments to appear: + +``` +{{ template "_internal/disqus.html" . }} +``` + +## Comments Alternatives + +There are a few alternatives to commenting on static sites for those who do not want to use Disqus: + +* [Staticman](https://staticman.net/) +* [Talkyard](https://www.talkyard.io/blog-comments) (Open source, & serverless hosting) +* [IntenseDebate](https://intensedebate.com/) +* [Graph Comment][] +* [Muut](https://muut.com/) +* [Isso](https://posativ.org/isso/) (Self-hosted, Python) + * [Tutorial on Implementing Isso with Hugo][issotutorial] +* [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues) +* [Remark](https://github.com/umputun/remark) (Open source, Golang, Easy to run docker) +* [Commento](https://commento.io/) (Open Source, available as a service, local install, or docker image) +* [Hyvor Talk](https://talk.hyvor.com/) (Available as a service) + + +[configuration]: /getting-started/configuration/ +[disquspartial]: /templates/partials/#disqus +[disqussetup]: https://disqus.com/profile/signup/ +[forum]: https://discourse.gohugo.io +[front matter]: /content-management/front-matter/ +[Graph Comment]: https://graphcomment.com/ +[kaijuissue]: https://github.com/spf13/kaiju/issues/new +[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/ +[partials]: /templates/partials/ +[MongoDB]: https://www.mongodb.com/ +[tweet]: https://twitter.com/spf13 diff --git a/exampleSite/content/en/documentation/explanation/content-management/cross-references.md b/exampleSite/content/en/documentation/explanation/content-management/cross-references.md new file mode 100644 index 0000000..81287a6 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/cross-references.md @@ -0,0 +1,126 @@ +--- +title: Links and Cross References +description: Shortcodes for creating links to documents. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-31 +categories: [content management] +keywords: ["cross references","references", "anchors", "urls"] + +weight: 100 #rem +aliases: [/extras/crossreferences/] +toc: true +--- + +The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively. + +## Use `ref` and `relref` + +```go-html-template +{{</* ref "document" */>}} +{{</* ref "document#anchor" */>}} +{{</* ref "document.md" */>}} +{{</* ref "document.md#anchor" */>}} +{{</* ref "#anchor" */>}} +{{</* ref "/blog/my-post" */>}} +{{</* ref "/blog/my-post.md" */>}} +{{</* relref "document" */>}} +{{</* relref "document.md" */>}} +{{</* relref "#anchor" */>}} +{{</* relref "/blog/my-post.md" */>}} +``` + +To generate a hyperlink using `ref` or `relref` in markdown: + +```md +[About]({{</* ref "/page/about" */>}} "About Us") +``` + +The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. + +**Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. + +Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below. + +### Link to another language version + +To link to another language version of a document, use this syntax: + +```go-html-template +{{</* relref path="document.md" lang="ja" */>}} +``` + +### Get another Output Format + +To link to another Output Format of a document, use this syntax: + +```go-html-template +{{</* relref path="document.md" outputFormat="rss" */>}} +``` + +### Heading IDs + +When using Markdown document types, Hugo generates element IDs for every heading on a page. For example: + +```md +## Reference +``` + +produces this HTML: + +```html +<h2 id="reference">Reference</h2> +``` + +Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes: + +```go-html-template +{{</* ref "document.md#reference" */>}} +{{</* relref "document.md#reference" */>}} +``` + +Generate a custom heading ID by including an attribute. For example: + +```md +## Reference A {#foo} +## Reference B {id="bar"} +``` + +produces this HTML: + +```html +<h2 id="foo">Reference A</h2> +<h2 id="bar">Reference B</h2> +``` + +Hugo will generate unique element IDs if the same heading appears more than once on a page. For example: + +```md +## Reference +## Reference +## Reference +``` + +produces this HTML: + +```html +<h2 id="reference">Reference</h2> +<h2 id="reference-1">Reference</h2> +<h2 id="reference-2">Reference</h2> +``` + +## Ref and RelRef Configuration + +The behavior can, since Hugo 0.45, be configured in `config.toml`: + +refLinksErrorLevel ("ERROR") +: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). + +refLinksNotFoundURL +: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. + + +[lists]: /templates/lists/ +[output formats]: /templates/output-formats/ +[shortcode]: /content-management/shortcodes/ +[bfext]: /content-management/formats/#blackfriday-extensions diff --git a/exampleSite/content/en/documentation/explanation/content-management/formats.md b/exampleSite/content/en/documentation/explanation/content-management/formats.md new file mode 100644 index 0000000..916b6ec --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/formats.md @@ -0,0 +1,177 @@ +--- +title: Content Formats +linktitle: Content Formats +description: Both HTML and Markdown are supported content formats. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-04-06 +categories: [content management] +keywords: [markdown, asciidoc, mmark, pandoc, content format] + +weight: 20 #rem +draft: false +aliases: + [ + /content/markdown-extras/, + /content/supported-formats/, + /doc/supported-formats/, + ] +toc: true +--- + +You can put any file type into your `/content` directories, but Hugo uses the `markup` front matter value if set or the file extension (see `Markup identifiers` in the table below) to determine if the markup needs to be processed, e.g.:. + +- Markdown converted to HTML +- [Shortcodes](/content-management/shortcodes/) processed +- Layout applied + +```goat + + . . . .--- 1 .-- 1 / 1 + / \ | | .---+ .-+ + + / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2 + + + | | | | ---+ ---+ + + / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3 + / \ / \ | | | | | | | | '---+ '-+ + + 1 7 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4 + +``` + +## List of content formats + +The current list of content formats in Hugo: + +| Name | Markup identifiers | Comment | +| -------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Goldmark | md, markdown, goldmark | Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).{{< new-in "0.60.0" >}} | +| Blackfriday | blackfriday | Blackfriday will eventually be deprecated. | +| MMark | mmark | Mmark is deprecated and will be removed in a future release. | +| Emacs Org-Mode | org | See [go-org](https://github.com/niklasfasching/go-org). | +| AsciiDoc | asciidocext, adoc, ad | Needs [Asciidoctor][ascii] installed. | +| RST | rst | Needs [RST](http://docutils.sourceforge.net/rst.html) installed. | +| Pandoc | pandoc, pdc | Needs [Pandoc](https://www.pandoc.org/) installed. | +| HTML | html, htm | To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is. | + +The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/). + +## External Helpers + +Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files, +Hugo will try to call the `asciidoctor` command. This means that you will have to install the associated +tool on your machine to be able to use these formats. + +Hugo passes reasonable default arguments to these external helpers by default: + +- `asciidoctor`: `--no-header-footer -` +- `rst2html`: `--leave-comments --initial-header-level=2` +- `pandoc`: `--mathjax` + +{{% warning "Performance of External Helpers" %}} +Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome. +{{% /warning %}} + +### External Helper AsciiDoc + +[AsciiDoc](https://github.com/asciidoc/asciidoc) implementation EOLs in Jan 2020 and is no longer supported. +AsciiDoc development is being continued under [Asciidoctor](https://github.com/asciidoctor). The format AsciiDoc +remains of course. Please continue with the implementation Asciidoctor. + +### External Helper Asciidoctor + +The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo. +[See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/). Make sure that also all +optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are installed if required. + +{{% note %}} +External `asciidoctor` command requires Hugo rendering to _disk_ to a specific destination directory. It is required to run Hugo with the command option `--destination`. +{{% /note %}} + +Some [Asciidoctor](https://asciidoctor.org/man/asciidoctor/) parameters can be customized in Hugo: + +| Parameter | Comment | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| backend | Don't change this unless you know what you are doing. | +| doctype | Currently, the only document type supported in Hugo is `article`. | +| extensions | Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, `asciidoctor-question`, `asciidoctor-rouge`. | +| attributes | Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See [Asciidoctor's attributes](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions). | +| noHeaderOrFooter | Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don't change this unless you know what you are doing. | +| safeMode | Safe mode level `unsafe`, `safe`, `server` or `secure`. Don't change this unless you know what you are doing. | +| sectionNumbers | Auto-number section titles. | +| verbose | Verbosely print processing information and configuration file checks to stderr. | +| trace | Include backtrace information on errors. | +| failureLevel | The minimum logging level that triggers a non-zero exit code (failure). | + +Hugo provides additional settings that don't map directly to Asciidoctor's CLI options: + +workingFolderCurrent +: Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [include](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) will work with relative paths. This setting uses the `asciidoctor` cli parameter `--base-dir` and attribute `outdir=`. For rendering diagrams with [asciidoctor-diagram](https://asciidoctor.org/docs/asciidoctor-diagram/), `workingFolderCurrent` must be set to `true`. + +preserveTOC +: By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable [`.TableOfContents`](/content-management/toc/) to enable further customization and better integration with the various Hugo themes. This option can be set to `true` to preserve Asciidoctor's TOC in the generated page. + +Below are all the AsciiDoc related settings in Hugo with their default values: + +{{< code-toggle config="markup.asciidocExt" />}} + +Example of how to set extensions and attributes: + +``` + +[markup.asciidocExt] +extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] +workingFolderCurrent = true +[markup.asciidocExt.attributes] +my-base-url = "https://example.com/" +my-attribute-name = "my value" + +``` + +In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all +parameters. Run Hugo with `-v`. You will get an output like + +``` + +INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ... + +``` + +## Learn Markdown + +Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running: + +- [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball] +- [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet] +- [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial] +- [The Markdown Guide, Matt Cone][mdguide] + +[`emojify` function]: /functions/emojify/ +[ascii]: https://asciidoctor.org/ +[bfconfig]: /getting-started/configuration/#configuring-blackfriday-rendering +[blackfriday]: https://github.com/russross/blackfriday +[mmark]: https://github.com/miekg/mmark +[config]: /getting-started/configuration/ +[developer tools]: /tools/ +[emojis]: https://www.webpagefx.com/tools/emoji-cheat-sheet/ +[fireball]: https://daringfireball.net/projects/markdown/ +[gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax +[helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65 +[hl]: /content-management/syntax-highlighting/ +[hlsc]: /content-management/shortcodes/#highlight +[hugocss]: /css/style.css +[ietf]: https://tools.ietf.org/html/ +[mathjaxdocs]: https://docs.mathjax.org/en/latest/ +[mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet +[mdguide]: https://www.markdownguide.org/ +[mdtutorial]: https://www.markdowntutorial.com/ +[miek gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/ +[mmark]: https://github.com/mmarkdown/mmark +[org]: https://orgmode.org/ +[pandoc]: https://www.pandoc.org/ +[pygments]: https://pygments.org/ +[rest]: https://docutils.sourceforge.io/rst.html +[sc]: /content-management/shortcodes/ +[sct]: /templates/shortcode-templates/ + +``` + +``` diff --git a/exampleSite/content/en/documentation/explanation/content-management/front-matter.md b/exampleSite/content/en/documentation/explanation/content-management/front-matter.md new file mode 100644 index 0000000..2ecf83f --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/front-matter.md @@ -0,0 +1,244 @@ +--- +title: Front Matter +linktitle: +description: Hugo allows you to add front matter in yaml, toml, or json to your content files. +date: 2017-01-09 +publishdate: 2017-01-09 +lastmod: 2017-02-24 +categories: [content management] +keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"] + +weight: 30 #rem +draft: false +aliases: [/content/front-matter/] +toc: true +--- + +**Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength. + +{{< youtube Yh2xKRJGff4 >}} + +## Front Matter Formats + +Hugo supports four formats for front matter, each with their own identifying tokens. + +TOML +: identified by opening and closing `+++`. + +YAML +: identified by opening and closing `---`. + +JSON +: a single JSON object surrounded by '`{`' and '`}`', followed by a new line. + +ORG +: a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section. + Keyword values can be either strings (`#+KEY: VALUE`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`). + +### Example + +{{< code-toggle >}} +title = "spf13-vim 3.0 release and new website" +description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." +tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] +date = "2012-04-06" +categories = [ + "Development", + "VIM" +] +slug = "spf13-vim-3-0-release-and-new-website" +{{< /code-toggle >}} + +## Front Matter Variables + +### Predefined + +There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates. + +aliases +: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details. + +audio +: an array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`. + +cascade +: a map of Front Matter keys whose values are passed down to the page's descendents unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details. + +date +: the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behaviour is configurable. + +description +: the description for the content. + +draft +: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command. + +expiryDate +: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command. + +headless +: if `true`, sets a leaf bundle to be [headless][headless-bundle]. + +images +: an array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`. + +isCJKLanguage +: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages. + +keywords +: the meta keywords for the content. + +layout +: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See ["Defining a Content Type"][definetype] + +lastmod +: the datetime at which the content was last modified. + +linkTitle +: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle]. + +markup +: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown. + +outputs +: allows you to specify output formats specific to the content. See [output formats][outputs]. + +publishDate +: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`. + +resources +: used for configuring page bundle resources. See [Page Resources][page-resources]. + +series +: an array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`. + +slug +: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename. + +summary +: text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section. + +title +: the title for the content. + +type +: the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter. + +url +: the full path to the content from the web root. It makes no assumptions about the path of the content file. It also ignores any language prefixes of +the multilingual feature. + +videos +: an array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`. + +weight +: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight. + +\<taxonomies\> +: field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. _Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables._ + +{{% note "Hugo's Default URL Destinations" %}} +If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors. +{{% /note %}} + +### User-Defined + +You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates. + +The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates. + +{{< code-toggle copy="false" >}} +include_toc: true +show_comments: false +{{</ code-toggle >}} + +## Front Matter Cascade + +Any node or section can pass down to descendents a set of Front Matter values as long as defined underneath the reserved `cascade` Front Matter key. + +### Target Specific Pages + +{{< new-in "0.76.0" >}} + +Since Hugo 0.76 the `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets. + +{{< code-toggle copy="false" >}} +title ="Blog" +[[cascade]] +background = "yosemite.jpg" +[cascade._target] +path="/blog/**" +lang="en" +kind="page" +[[cascade]] +background = "goldenbridge.jpg" +[cascade._target] +kind="section" +{{</ code-toggle >}} + +Keywords available for `_target`: + +path +: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching support double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down. + +kind +: A Glob pattern matching the Page's Kind(s), e.g. "{home,section}". + +lang +: A Glob pattern matching the Page's language, e.g. "{en,sv}". + +Any of the above can be omitted. + +### Example + +In `content/blog/_index.md` + +{{< code-toggle copy="false" >}} +title: Blog +cascade: + banner: images/typewriter.jpg +{{</ code-toggle >}} + +With the above example the Blog section page and its descendents will return `images/typewriter.jpg` when `.Params.banner` is invoked unless: + +- Said descendent has its own `banner` value set +- Or a closer ancestor node has its own `cascade.banner` value set. + + + +## Order Content Through Front Matter + +You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views. + +## Override Global Markdown Configuration + +It's possible to set some options for Markdown rendering in a content's front matter as an override to the [BlackFriday rendering options set in your project configuration][config]. + +## Front Matter Format Specs + +* [TOML Spec][toml] +* [YAML Spec][yaml] +* [JSON Spec][json] + +[variables]: /variables/ +[aliases]: /content-management/urls/#aliases +[archetype]: /content-management/archetypes/ +[bylinktitle]: /templates/lists/#by-link-title +[config]: /getting-started/configuration/ "Hugo documentation for site configuration" +[content type]: /content-management/types/ +[contentorg]: /content-management/organization/ +[definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter" +[headless-bundle]: /content-management/page-bundles/#headless-bundle +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[lists]: /templates/lists/#ordering-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter." +[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating." +[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates" +[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating" +[page-resources]: /content-management/page-resources/ +[pagevars]: /variables/page/ +[section]: /content-management/sections/ +[taxweight]: /content-management/taxonomies/ +[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language" +[urls]: /content-management/urls/ +[variables]: /variables/ +[yaml]: https://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language" diff --git a/exampleSite/content/en/documentation/explanation/content-management/image-processing/index.md b/exampleSite/content/en/documentation/explanation/content-management/image-processing/index.md new file mode 100644 index 0000000..a432b98 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/image-processing/index.md @@ -0,0 +1,323 @@ +--- +title: "Image Processing" +description: "Image Page resources can be resized and cropped." +date: 2018-01-24T13:10:00-05:00 +linktitle: "Image Processing" +categories: ["content management"] +keywords: [resources, images] +weight: 4004 +draft: false +toc: true +menu: + docs: + parent: "content-management" + weight: 32 +--- + +## The Image Page Resource + +The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below do not work on images inside your `/static` folder. + +To print all images paths in a [Page Bundle]({{< relref "/content-management/organization#page-bundles" >}}): + +```go-html-template +{{ with .Resources.ByType "image" }} +{{ range . }} +{{ .RelPermalink }} +{{ end }} +{{ end }} + +``` + +## The Image Resource + +The `image` resource can also be retrieved from a [global resource]({{< relref "/hugo-pipes/introduction#from-file-to-resource" >}}) + +```go-html-template +{{- $image := resources.Get "images/logo.jpg" -}} +``` + +## Image Processing Methods + +The `image` resource implements the `Resize`, `Fit`, `Fill`, and `Filter` methods, each returning a transformed image using the specified dimensions and processing options. + +{{% note %}} +Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`](#exif) method with the _original_ image to extract EXIF metadata from JPEG or TIFF images. +{{% /note %}} + +### Resize + +Resizes the image to the specified width and height. + +```go +// Resize to a width of 600px and preserve ratio +{{ $image := $resource.Resize "600x" }} + +// Resize to a height of 400px and preserve ratio +{{ $image := $resource.Resize "x400" }} + +// Resize to a width 600px and a height of 400px +{{ $image := $resource.Resize "600x400" }} +``` + +### Fit + +Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required. + +```go +{{ $image := $resource.Fit "600x400" }} +``` + +### Fill + +Resize and crop the image to match the given dimensions. Both height and width are required. + +```go +{{ $image := $resource.Fill "600x400" }} +``` + +### Filter + +Apply one or more filters to your image. See [Image Filters](/functions/images/#image-filters) for a full list. + +```go-html-template +{{ $img = $img.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +The above can also be written in a more functional style using pipes: + +```go-html-template +{{ $img = $img | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +The filters will be applied in the given order. + +Sometimes it can be useful to create the filter chain once and then reuse it: + +```go-html-template +{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }} +{{ $img1 = $img1.Filter $filters }} +{{ $img2 = $img2.Filter $filters }} +``` + +### Exif + +Provides an [Exif](https://en.wikipedia.org/wiki/Exif) object with metadata about the image. + +Note that this is only supported for JPEG and TIFF images, so it's recommended to wrap the access with a `with`, e.g.: + +```go-html-template +{{ with $img.Exif }} +Date: {{ .Date }} +Lat/Long: {{ .Lat}}/{{ .Long }} +Tags: +{{ range $k, $v := .Tags }} +TAG: {{ $k }}: {{ $v }} +{{ end }} +{{ end }} +``` + +Or individually access EXIF data with dot access, e.g.: + +```go-html-template +{{ with $src.Exif }} + <ul> + {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }} + {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.NumFmt 2 . }}</li>{{ end }} + {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.NumFmt 2 . }}</li>{{ end }} + {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }} + {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }} + {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }} + {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }} + {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }} + </ul> +{{ end }} +``` + +Some fields may need to be formatted with [`lang.NumFmt`]({{< relref "functions/numfmt" >}}) function to prevent display like `Aperture: 2.278934289` instead of `Aperture: 2.28`. + +#### Exif fields + +Date +: "photo taken" date/time + +Lat +: "photo taken where", GPS latitude + +Long +: "photo taken where", GPS longitude + +See [Image Processing Config](#image-processing-config) for how to configure what gets included in Exif. + +## Image Processing Options + +In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options. + +### Background Color + +The background color to fill into the transparency layer. This is mostly useful when converting to a format that does not support transparency, e.g. `JPEG`. + +You can set the background color to use with a 3 or 6 digit hex code starting with `#`. + +```go +{{ $image.Resize "600x jpg #b31280" }} +``` + +For color codes, see https://www.google.com/search?q=color+picker + +**Note** that you also set a default background color to use, see [Image Processing Config](#image-processing-config). + +### JPEG Quality + +Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. + +```go +{{ $image.Resize "600x q50" }} +``` + +### Rotate + +Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. + +```go +{{ $image.Resize "600x r90" }} +``` + +### Anchor + +Only relevant for the `Fill` method. This is useful for thumbnail generation where the main motive is located in, say, the left corner. + +Valid values are `Smart`, `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. + +Default value is `Smart`, which uses [Smartcrop](https://github.com/muesli/smartcrop) to determine the best crop. + +```go +{{ $image.Fill "300x200 BottomLeft" }} +``` + +### Resample Filter + +Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. + +Examples are: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`. + +See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. + +```go +{{ $image.Resize "600x400 Gaussian" }} +``` + +### Target Format + +By default the images is encoded in the source format, but you can set the target format as an option. + +Valid values are `jpg`, `png`, `tif`, `bmp`, and `gif`. + +```go +{{ $image.Resize "600x jpg" }} +``` + +## Image Processing Examples + +_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ + +{{< imgproc sunset Resize "300x" />}} + +{{< imgproc sunset Fill "90x120 left" />}} + +{{< imgproc sunset Fill "90x120 right" />}} + +{{< imgproc sunset Fit "90x90" />}} + +{{< imgproc sunset Resize "300x q10" />}} + +This is the shortcode used in the examples above: + +{{< code file="layouts/shortcodes/imgproc.html" >}} +{{< readfile file="layouts/shortcodes/imgproc.html" >}} +{{< /code >}} + +And it is used like this: + +```go-html-template +{{</* imgproc sunset Resize "300x" /*/>}} +``` + +{{% note %}} +**Tip:** Note the self-closing shortcode syntax above. The `imgproc` shortcode can be called both with and without **inner content**. +{{% /note %}} + +## Image Processing Config + +You can configure an `imaging` section in `config.toml` with default image processing options: + +```toml +[imaging] +# Default resample filter used for resizing. Default is Box, +# a simple and fast averaging filter appropriate for downscaling. +# See https://github.com/disintegration/imaging +resampleFilter = "box" + +# Default JPEG quality setting. Default is 75. +quality = 75 + +# Anchor used when cropping pictures. +# Default is "smart" which does Smart Cropping, using https://github.com/muesli/smartcrop +# Smart Cropping is content aware and tries to find the best crop for each image. +# Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight +anchor = "smart" + +# Default background color. +# Hugo will preserve transparency for target formats that supports it, +# but will fall back to this color for JPEG. +# Expects a standard HEX color string with 3 or 6 digits. +# See https://www.google.com/search?q=color+picker +bgColor = "#ffffff" + +[imaging.exif] + # Regexp matching the fields you want to Exclude from the (massive) set of Exif info +# available. As we cache this info to disk, this is for performance and +# disk space reasons more than anything. +# If you want it all, put ".*" in this config setting. +# Note that if neither this or ExcludeFields is set, Hugo will return a small +# default set. +includeFields = "" + +# Regexp matching the Exif fields you want to exclude. This may be easier to use +# than IncludeFields above, depending on what you want. +excludeFields = "" + +# Hugo extracts the "photo taken" date/time into .Date by default. +# Set this to true to turn it off. +disableDate = false + +# Hugo extracts the "photo taken where" (GPS latitude and longitude) into +# .Long and .Lat. Set this to true to turn it off. +disableLatLong = false + + +``` + +## Smart Cropping of Images + +By default, Hugo will use [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future. + +An example using the sunset image from above: + +{{< imgproc sunset Fill "200x200 smart" />}} + +## Image Processing Performance Consideration + +Processed images are stored below `<project-dir>/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. + +If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. + +To clean up, run: + +```bash +hugo --gc +``` + +{{% note %}} +**GC** is short for **Garbage Collection**. +{{% /note %}} diff --git a/exampleSite/content/en/documentation/explanation/content-management/image-processing/sunset.jpg b/exampleSite/content/en/documentation/explanation/content-management/image-processing/sunset.jpg Binary files differnew file mode 100644 index 0000000..4dbcc08 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/image-processing/sunset.jpg diff --git a/exampleSite/content/en/documentation/explanation/content-management/menus.md b/exampleSite/content/en/documentation/explanation/content-management/menus.md new file mode 100644 index 0000000..83bd281 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/menus.md @@ -0,0 +1,129 @@ +--- +title: +weight: 120 #rem +aliases: [/extras/menus/] +toc: true +--- + +{{% note "Lazy Blogger"%}} +If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers). +{{% /note %}} + +You can do this: + +* Place content in one or many menus +* Handle nested menus with unlimited depth +* Create menu entries without being attached to any content +* Distinguish active element (and active branch) + +## What is a Menu in Hugo? + +A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`. + +{{% note "Menus on Multilingual Sites" %}} +If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus. +{{% /note %}} + +See the [Menu Entry Properties][me-props] for all the variables and functions related to a menu entry. + +## Add content to menus + +Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/). + +### Simple + +If all you need to do is add an entry to a menu, the simple form works well. + +#### A Single Menu + +``` +--- +menu: "main" +--- +``` + +#### Multiple Menus + +``` +--- +menu: ["main", "footer"] +--- +``` + +#### Advanced + + +``` +--- +menu: + docs: + parent: 'extras' + weight: 20 +--- +``` + +## Add Non-content Entries to a Menu + +You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config]. + +Here’s an example snippet pulled from a configuration file: + +{{< code-toggle file="config" >}} +[[menu.main]] + name = "about hugo" + pre = "<i class='fa fa-heart'></i>" + weight = -110 + identifier = "about" + url = "/about/" +[[menu.main]] + name = "getting started" + pre = "<i class='fa fa-road'></i>" + post = "<span class='alert'>New!</span>" + weight = -100 + url = "/getting-started/" +{{< /code-toggle >}} + +{{% note %}} +The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`. +{{% /note %}} + +## Nesting + +All nesting of content is done via the `parent` field. + +The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu). + +The following order is used to determine an Identifier: + +`.Name > .LinkTitle > .Title` + +This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed. + +In this example, the top level of the menu is defined in your [site `config` file][config]. All content entries are attached to one of these entries via the `.Parent` field. + +## Params + +You can also add user-defined content to menu items via the `params` field. + +A common use case is to define a custom param to add a css class to a specific menu item. + +{{< code-toggle file="config" >}} +[[menu.main]] + name = "about hugo" + pre = "<i class='fa fa-heart'></i>" + weight = -110 + identifier = "about" + url = "/about/" + [menu.main.params] + class = "highlight-menu-item" +{{</ code-toggle >}} + + +## Render Menus + +See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates. + +[config]: /getting-started/configuration/ +[multilingual]: /content-management/multilingual/ +[sitevars]: /variables/ +[me-props]: /variables/menus/ diff --git a/exampleSite/content/en/documentation/explanation/content-management/multilingual.md b/exampleSite/content/en/documentation/explanation/content-management/multilingual.md new file mode 100644 index 0000000..1f53372 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/multilingual.md @@ -0,0 +1,497 @@ +--- +title: Multilingual Mode +linktitle: Multilingual and i18n +description: Hugo supports the creation of websites with multiple languages side by side. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-01-10 +categories: [content management] +keywords: [multilingual,i18n, internationalization] + +weight: 150 #rem +draft: false +aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/] +toc: true +--- + +You should define the available languages in a `languages` section in your site configuration. + +> Also See [Hugo Multilingual Part 1: Content translation](https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/) + +## Configure Languages + +The following is an example of a site configuration for a multilingual Hugo project: + +{{< code-toggle file="config" >}} +defaultContentLanguage = "en" +copyright = "Everything is mine" + +[params] +[params.navigation] +help = "Help" + +[languages] +[languages.en] +title = "My blog" +weight = 1 +[languages.en.params] +linkedin = "https://linkedin.com/whoever" + +[languages.fr] +title = "Mon blogue" +weight = 2 +[languages.fr.params] +linkedin = "https://linkedin.com/fr/whoever" +[languages.fr.params.navigation] +help = "Aide" + +[languages.ar] +title = "مدونتي" +weight = 2 +languagedirection = "rtl" + +[languages.pt-pt] +title = "O meu blog" +weight = 3 +{{< /code-toggle >}} + +Anything not defined in a `languages` block will fall back to the global value for that key (e.g., `copyright` for the English `en` language). This also works for `params`, as demonstrated with `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set. + +With the configuration above, all content, sitemap, RSS feeds, paginations, +and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French. + +When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation. + +`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`. + +If the default language needs to be rendered below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`. + +Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. + +**Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `defaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344) + +### Disable a Language + +You can disable one or more languages. This can be useful when working on a new translation. + +```toml +disableLanguages = ["fr", "ja"] +``` + +Note that you cannot disable the default content language. + +We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables): + +```bash +HUGO_DISABLELANGUAGES="fr ja" hugo +``` +If you have already a list of disabled languages in `config.toml`, you can enable them in development like this: + +```bash +HUGO_DISABLELANGUAGES=" " hugo server +``` + + +### Configure Multilingual Multihost + +From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. + +This means that you can now configure a `baseURL` per `language`: + + +> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. + +Example: + +{{< code-toggle file="config" >}} +[languages] +[languages.fr] +baseURL = "https://example.fr" +languageName = "Français" +weight = 1 +title = "En Français" + +[languages.en] +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" +{{</ code-toggle >}} + +With the above, the two sites will be generated into `public` with their own root: + +```bash +public +├── en +└── fr +``` + +**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.** + +When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console: + +```bash +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) +Press Ctrl+C to stop +``` + +Live reload and `--navigateToChanged` between the servers work as expected. + +### Taxonomies and Blackfriday + +Taxonomies and [Blackfriday configuration][config] can also be set per language: + + +{{< code-toggle file="config" >}} +[Taxonomies] +tag = "tags" + +[blackfriday] +angledQuotes = true +hrefTargetBlank = true + +[languages] +[languages.en] +weight = 1 +title = "English" +[languages.en.blackfriday] +angledQuotes = false + +[languages.fr] +weight = 2 +title = "Français" +[languages.fr.Taxonomies] +plaque = "plaques" +{{</ code-toggle >}} + +## Translate Your Content + +There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations. + +### Translation by filename + +Considering the following example: + +1. `/content/about.en.md` +2. `/content/about.fr.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the language code added as a __suffix to the filename__. + +By having the same **path and base filename**, the content pieces are __linked__ together as translated pages. + +{{< note >}} +If a file has no language code, it will be assigned the default language. +{{</ note >}} + +### Translation by content directory + +This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param. + +{{< code-toggle file="config" >}} + +languages: + en: + weight: 10 + languageName: "English" + contentDir: "content/english" + fr: + weight: 20 + languageName: "Français" + contentDir: "content/french" + +{{< /code-toggle >}} + +The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap. + +Considering the following example in conjunction with the configuration above: + +1. `/content/english/about.md` +2. `/content/french/about.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the content directory they are __placed__ in. + +By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages. + +### Bypassing default linking. + +Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location. + +Considering the following example: + +1. `/content/about-us.en.md` +2. `/content/om.nn.md` +3. `/content/presentation/a-propos.fr.md` + +```yaml +# set in all three pages +translationKey: "about" +``` + +By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages. + + +### Localizing permalinks + +Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory). + +To localize the URLs, the [`slug`]({{< ref "/content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "/content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file. + +For example, a French translation (`content/about.fr.md`) can have its own localized slug. + +{{< code-toggle >}} +Title: A Propos +slug: "a-propos" +{{< /code-toggle >}} + + +At render, Hugo will build both `/about/` and `/fr/a-propos/` while maintaining their translation linking. + +{{% note %}} +If using `url`, remember to include the language part as well: `/fr/compagnie/a-propos/`. +{{%/ note %}} + +### Page Bundles + +To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (markdown files, html files etc...). + +Therefore, from within a template, the page will have access to the files from all linked pages' bundles. + +If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows: + +* File from current language bundle, if present. +* First file found across bundles by order of language `Weight`. + +{{% note %}} +Page Bundle resources follow the same language assignment logic as content files, both by filename (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`). +{{%/ note %}} + +## Reference the Translated Content + +To create a list of links to translated content, use a template similar to the following: + +{{< code file="layouts/partials/i18nlist.html" >}} +{{ if .IsTranslated }} +<h4>{{ i18n "translations" }}</h4> +<ul> + {{ range .Translations }} + <li> + <a href="{{ .Permalink }}">{{ .Lang }}: {{ .Title }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, whether a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page. + +The above also uses the [`i18n` function][i18func] described in the next section. + +### List All Available Languages + +`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator: + + +{{< code file="layouts/partials/allLanguages.html" >}} +<ul> +{{ range $.Site.Home.AllTranslations }} +<li><a href="{{ .Permalink }}">{{ .Language.LanguageName }}</a></li> +{{ end }} +</ul> +{{< /code >}} + +## Translation of Strings + +Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows. + +Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc. + +{{% note %}} +From **Hugo 0.31** you no longer need to use a valid language code. It can be anything. + +See https://github.com/gohugoio/hugo/issues/3564 + +{{% /note %}} + +### Query basic translation + +From within your templates, use the `i18n` function like this: + +``` +{{ i18n "home" }} +``` + +The function will search for the `"home"` id from `i18n/en-US.toml` file: + +``` +[home] +other = "Home" +``` + +The result will be + +``` +Home +``` + +### Query a flexible translation with variables + +Often you will want to use to the page variables in the translations strings. To do that, pass on the `.` context when calling `i18n`: + +``` +{{ i18n "wordCount" . }} +``` + +The function will pass the `.` context to the `"wordCount"` id in `i18n/en-US.toml` file: + +``` +[wordCount] +other = "This article has {{ .WordCount }} words." +``` + +Assume `.WordCount` in the context has value is 101. The result will be: + +``` +This article has 101 words. +``` + +### Query a singular/plural translation + +In order to meet singular/plural requirement, you must pass a dictionary (map) with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property. + +``` +{{ i18n "readingTime" .ReadingTime }} +``` + +The function will read `.Count` from `.ReadingTime` and evaluate where the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file: + +``` +[readingTime] +one = "One minute to read" +other = "{{.Count}} minutes to read" +``` + +Assume `.ReadingTime.Count` in the context has value of 525600. The result will be: + +``` +525600 minutes to read +``` + +If `.ReadingTime.Count` in the context has value is 1. The result is: + +``` +One minutes to read +``` + +In case you need to pass custom data: (`(dict "Count" 25)` is minimum requirement) + +``` +{{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }} +``` + + +## Customize Dates + +At the time of this writing, Go does not yet have support for internationalized locales for dates, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content: + +~~~yaml +1: "janvier" +2: "février" +3: "mars" +4: "avril" +5: "mai" +6: "juin" +7: "juillet" +8: "août" +9: "septembre" +10: "octobre" +11: "novembre" +12: "décembre" +~~~ + +...then index the non-English date names in your templates like so: + +~~~html +<time class="post-date" datetime="{{ .Date.Format `2006-01-02T15:04:05Z07:00` | safeHTML }}"> + Article publié le {{ .Date.Day }} {{ index $.Site.Data.mois (printf "%d" .Date.Month) }} {{ .Date.Year }} (dernière modification le {{ .Lastmod.Day }} {{ index $.Site.Data.mois (printf "%d" .Lastmod.Month) }} {{ .Lastmod.Year }}) +</time> +~~~ + +This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file. + + +## +weight = 0 +languageName = "English" + +[[languages.en. +weight = 0 + + +[languages.de] +weight = 10 +languageName = "Deutsch" + +[[languages.de. +weight = 0 +``` + +The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu in the current language. Note that `absLangURL` below will link to the correct locale of your website. Without it, menu entries in all languages would link to the English version, since it's the default content language that resides in the root directory. + +``` +<ul> + {{- $currentPage := . -}} + {{ range .Site.Menus.main -}} + <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}"> + <a href="{{ .URL | absLangURL }}">{{ .Name }}</a> + </li> + {{- end }} +</ul> + +``` + +## Missing Translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments. +{{% /note %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + +To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: + +``` + hugo --i18n-warnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + +## Multilingual Themes support + +To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: + +* Come from the built-in `.Permalink` or `.RelPermalink` +* Be constructed with the [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** be prefixed with `{{ .LanguagePrefix }}` + +If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites). + +[abslangurl]: /functions/abslangurl +[config]: /getting-started/configuration/ +[contenttemplate]: /templates/single-page-templates/ +[go-i18n-source]: https://github.com/nicksnyder/go-i18n +[go-i18n]: https://github.com/nicksnyder/go-i18n +[homepage]: /templates/homepage/ +[i18func]: /functions/i18n/ +[menus]: /content-management/menus/ +[rellangurl]: /functions/rellangurl +[RFC 5646]: https://tools.ietf.org/html/rfc5646 +[singles]: /templates/single-page-templates/ diff --git a/exampleSite/content/en/documentation/explanation/content-management/organization/1-featured-content-bundles.png b/exampleSite/content/en/documentation/explanation/content-management/organization/1-featured-content-bundles.png Binary files differnew file mode 100644 index 0000000..501e671 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/organization/1-featured-content-bundles.png diff --git a/exampleSite/content/en/documentation/explanation/content-management/organization/index.md b/exampleSite/content/en/documentation/explanation/content-management/organization/index.md new file mode 100644 index 0000000..012a3ca --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/organization/index.md @@ -0,0 +1,237 @@ +--- +title: Content Organization +linktitle: Organization +description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [content management,fundamentals] +keywords: [sections,content,organization,bundle,resources] + +weight: 10 #rem +draft: false +aliases: [/content/sections/] +toc: true +--- + +## Page Bundles + +Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`. + +These terms are connected, and you also need to read about [Page Resources]({{< relref "/content-management/page-resources" >}}) and [Image Processing]({{< relref "/content-management/image-processing" >}}) to get the full picture. + +{{< imgproc 1-featured Resize "300x" >}} +The illustration shows 3 bundles. Note that the home page bundle cannot contain other content pages, but other files (images etc.) are fine. +{{< /imgproc >}} + + +{{% note %}} +The bundle documentation is **work in progress**. We will publish more comprehensive docs about this soon. +{{% /note %}} + + +# Organization of Content Source + + +In Hugo, your content should be organized in a manner that reflects the rendered website. + +While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections][]. + +Without any additional configuration, the following will just work: + +``` +. +└── content + └── about + | └── index.md // <- https://example.com/about/ + ├── posts + | ├── firstpost.md // <- https://example.com/posts/firstpost/ + | ├── happy + | | └── ness.md // <- https://example.com/posts/happy/ness/ + | └── secondpost.md // <- https://example.com/posts/secondpost/ + └── quote + ├── first.md // <- https://example.com/quote/first/ + └── second.md // <- https://example.com/quote/second/ +``` + +## Path Breakdown in Hugo + + +The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.com"` in your [site's configuration file][config]. + +### Index Pages: `_index.md` + +`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][]. + +{{% note %}} +**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/). +{{% /note %}} + +You can keep one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: + + +``` +. url +. ⊢--^-⊣ +. path slug +. ⊢--^-⊣⊢---^---⊣ +. filepath +. ⊢------^------⊣ +content/posts/_index.md +``` + +At build, this will output to the following destination with the associated values: + +``` + + url ("/posts/") + ⊢-^-⊣ + baseurl section ("posts") +⊢--------^---------⊣⊢-^-⊣ + permalink +⊢----------^-------------⊣ +https://example.com/posts/index.html +``` + +The [sections][] can be nested as deeply as you need. The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (i.e. `_index.md`). + + +### Single Pages in Sections + +Single content files in each of your sections are going to be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`: + + +``` + path ("posts/my-first-hugo-post.md") +. ⊢-----------^------------⊣ +. section slug +. ⊢-^-⊣⊢--------^----------⊣ +content/posts/my-first-hugo-post.md +``` + +When Hugo builds your site, the content will be outputted to the following destination: + +``` + + url ("/posts/my-first-hugo-post/") + ⊢------------^----------⊣ + baseurl section slug +⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ + permalink +⊢--------------------^---------------------⊣ +https://example.com/posts/my-first-hugo-post/index.html +``` + + +## Paths Explained + +The following concepts will provide more insight into the relationship between your project's organization and the default behaviors of Hugo when building the output website. + +### `section` + +A default content type is determined by a piece of content's section. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter. + +### `slug` + +A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by + +* the name of the content file (e.g., `lollapalooza.md`) OR +* front matter overrides + +### `path` + +A content's `path` is determined by the section's path to the file. The file `path` + +* is based on the path to the content's location AND +* does not include the slug + +### `url` + +The `url` is the relative URL for the piece of content. The `url` + +* is based on the content's location within the directory structure OR +* is defined in front matter and *overrides all the above* + +## Override Destination Paths via Front Matter + +Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored in the destination. + +There are times where you may need more control over your content. In these cases, there are fields that can be specified in the front matter to determine the destination of a specific piece of content. + +The following items are defined in this order for a specific reason: items explained further down in the list will override earlier items, and not all of these items can be defined in front matter: + +### `filename` + +This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`). + +### `slug` + +When defined in the front matter, the `slug` can take the place of the filename for the destination. + +{{< code file="content/posts/old-post.md" >}} +--- +title: A new post with the filename old-post.md +slug: "new-post" +--- +{{< /code >}} + +This will render to the following destination according to Hugo's default behavior: + +``` +example.com/posts/new-post/ +``` + +### `section` + +`section` is determined by a content's location on disk and *cannot* be specified in the front matter. See [sections][] for more information. + +### `type` + +A content's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types][]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts. + +{{< code file="content/posts/my-post.md" >}} +--- +title: My Post +type: new +layout: mylayout +--- +{{< /code >}} +<!-- See https://discourse.gohugo.io/t/path-not-works/6387 --> +<!-- ### `path`--> + +<!--`path` can be provided in the front matter. This will replace the actual path to the file on disk. Destination will create the destination with the same path, including the section. --> + +### `url` + +A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it provided in the front matter and will ignore the `--uglyURLs` setting in your site configuration: + +{{< code file="content/posts/old-url.md" >}} +--- +title: Old URL +url: /blog/new-url/ +--- +{{< /code >}} + +Assuming your `baseURL` is [configured][config] to `https://example.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination: + +``` +https://example.com/blog/new-url/ +``` + +You can see more information on how to control output paths in [URL Management][urls]. + +[config]: /getting-started/configuration/ +[formats]: /content-management/formats/ +[front matter]: /content-management/front-matter/ +[getpage]: /functions/getpage/ +[homepage template]: /templates/homepage/ +[homepage]: /templates/homepage/ +[lists]: /templates/lists/ +[pretty]: /content-management/urls/#pretty-urls +[section templates]: /templates/section-templates/ +[sections]: /content-management/sections/ +[singles]: /templates/single-page-templates/ +[taxonomy templates]: /templates/taxonomy-templates/ +[taxonomy terms templates]: /templates/taxonomy-templates/ +[types]: /content-management/types/ +[urls]: /content-management/urls/ diff --git a/exampleSite/content/en/documentation/explanation/content-management/page-bundles.md b/exampleSite/content/en/documentation/explanation/content-management/page-bundles.md new file mode 100644 index 0000000..9561ea2 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/page-bundles.md @@ -0,0 +1,188 @@ +--- +title : "Page Bundles" +description : "Content organization using Page Bundles" +date : 2018-01-24T13:09:00-05:00 +linktitle : "Page Bundles" +keywords : ["page", "bundle", "leaf", "branch"] +categories : ["content management"] +toc : true +menu : + docs: + identifier : "page-bundles" + parent : "content-management" + weight : 11 +--- + +Page Bundles are a way to group [Page Resources](/content-management/page-resources/). + +A Page Bundle can be one of: + +- Leaf Bundle (leaf means it has no children) +- Branch Bundle (home page, section, taxonomy terms, taxonomy list) + +| | Leaf Bundle | Branch Bundle | +|-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) | +| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] | +| Allowed Resources | Page and non-page (like images, pdf, etc.) types | Only non-page (like images, pdf, etc.) types | +| Where can the Resources live? | At any directory level within the leaf bundle directory. | Only in the directory level **of** the branch bundle directory i.e. the directory containing the `_index.md` ([ref](https://discourse.gohugo.io/t/question-about-content-folder-structure/11822/4?u=kaushalmodi)). | +| Layout type | `single` | `list` | +| Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it | +| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` | +| Content from non-index page files... | Accessed only as page resources | Accessed only as regular pages | + + +## Leaf Bundles {#leaf-bundles} + +A _Leaf Bundle_ is a directory at any hierarchy within the `content/` +directory, that contains an **`index.md`** file. + +### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization} + +```text +content/ +├── about +│ ├── index.md +├── posts +│ ├── my-post +│ │ ├── content1.md +│ │ ├── content2.md +│ │ ├── image1.jpg +│ │ ├── image2.png +│ │ └── index.md +│ └── my-other-post +│ └── index.md +│ +└── another-section + ├── .. + └── not-a-leaf-bundle + ├── .. + └── another-leaf-bundle + └── index.md +``` + +In the above example `content/` directory, there are four leaf +bundles: + +about +: This leaf bundle is at the root level (directly under + `content` directory) and has only the `index.md`. + +my-post +: This leaf bundle has the `index.md`, two other content + Markdown files and two image files. + +image1 +: This image is a page resource of `my-post` + and only available in `my-post/index.md` resources. + +image2 +: This image is a page resource of `my-post` + and only available in `my-post/index.md` resources. + +my-other-post +: This leaf bundle has only the `index.md`. + +another-leaf-bundle +: This leaf bundle is nested under couple of + directories. This bundle also has only the `index.md`. + +{{% note %}} +The hierarchy depth at which a leaf bundle is created does not matter, +as long as it is not inside another **leaf** bundle. +{{% /note %}} + + +### Headless Bundle {#headless-bundle} + +A headless bundle is a bundle that is configured to not get published +anywhere: + +- It will have no `Permalink` and no rendered HTML in `public/`. +- It will not be part of `.Site.RegularPages`, etc. + +But you can get it by `.Site.GetPage`. Here is an example: + +```go-html-template +{{ $headless := .Site.GetPage "/some-headless-bundle" }} +{{ $reusablePages := $headless.Resources.Match "author*" }} +<h2>Authors</h2> +{{ range $reusablePages }} + <h3>{{ .Title }}</h3> + {{ .Content }} +{{ end }} +``` + +_In this example, we are assuming the `some-headless-bundle` to be a headless + bundle containing one or more **page** resources whose `.Name` matches + `"author*"`._ + +Explanation of the above example: + +1. Get the `some-headless-bundle` Page "object". +2. Collect a *slice* of resources in this *Page Bundle* that matches + `"author*"` using `.Resources.Match`. +3. Loop through that *slice* of nested pages, and output their `.Title` and + `.Content`. + +--- + +A leaf bundle can be made headless by adding below in the Front Matter +(in the `index.md`): + +```toml +headless = true +``` + +There are many use cases of such headless page bundles: + +- Shared media galleries +- Reusable page content "snippets" + + +## Branch Bundles {#branch-bundles} + +A _Branch Bundle_ is any directory at any hierarchy within the +`content/` directory, that contains at least an **`_index.md`** file. + +This `_index.md` can also be directly under the `content/` directory. + +{{% note %}} +Here `md` (markdown) is used just as an example. You can use any file +type as a content resource as long as it is a content type recognized by Hugo. +{{% /note %}} + + +### Examples of Branch Bundle organization {#examples-of-branch-bundle-organization} + +```text +content/ +├── branch-bundle-1 +│ ├── branch-content1.md +│ ├── branch-content2.md +│ ├── image1.jpg +│ ├── image2.png +│ └── _index.md +└── branch-bundle-2 + ├── _index.md + └── a-leaf-bundle + └── index.md +``` + +In the above example `content/` directory, there are two branch +bundles (and a leaf bundle): + +`branch-bundle-1` +: This branch bundle has the `_index.md`, two + other content Markdown files and two image files. + +`branch-bundle-2` +: This branch bundle has the `_index.md` and a + nested leaf bundle. + +{{% note %}} +The hierarchy depth at which a branch bundle is created does not +matter. +{{% /note %}} + +[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any valid MIME type. diff --git a/exampleSite/content/en/documentation/explanation/content-management/page-resources.md b/exampleSite/content/en/documentation/explanation/content-management/page-resources.md new file mode 100644 index 0000000..bdc73a7 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/page-resources.md @@ -0,0 +1,171 @@ +--- +title : "Page Resources" +description : "Page Resources -- images, other pages, documents etc. -- have page-relative URLs and their own metadata." +date: 2018-01-24 +categories: ["content management"] +keywords: [bundle,content,resources] +weight: 4003 +draft: false +toc: true +linktitle: "Page Resources" +menu: + docs: + parent: "content-management" + weight: 31 +--- + +Page resources are available for [page bundles]({{< relref "/content-management/page-bundles" >}}) only, +i.e. a directory with either a `index.md`, or `_index.md` file at its root. Resources are only attached to +the lowest page they are bundled with, and simple which names does not contain `index.md` are not attached any resource. + +## Properties + +ResourceType +: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`. + +{{< new-in "0.80.0" >}} Note that we in Hugo `v0.80.0` fixed a bug where non-image resources (e.g. video) would return the MIME sub type, e.g. `json`. + +Name +: Default value is the filename (relative to the owning page). Can be set in front matter. + +Title +: Default value is the same as `.Name`. Can be set in front matter. + +Permalink +: The absolute URL to the resource. Resources of type `page` will have no value. + +RelPermalink +: The relative URL to the resource. Resources of type `page` will have no value. + +Content +: The content of the resource itself. For most resources, this returns a string with the contents of the file. This can be used to inline some resources, such as `<script>{{ (.Resources.GetMatch "myscript.js").Content | safeJS }}</script>` or `<img src="{{ (.Resources.GetMatch "mylogo.png").Content | base64Encode }}">`. + +MediaType +: The MIME type of the resource, such as `image/jpeg`. + +MediaType.MainType +: The main type of the resource's MIME type. For example, a file of MIME type `application/pdf` has for MainType `application`. + +MediaType.SubType +: The subtype of the resource's MIME type. For example, a file of MIME type `application/pdf` has for SubType `pdf`. Note that this is not the same as the file extension - PowerPoint files have a subtype of `vnd.mspowerpoint`. + +MediaType.Suffixes +: A slice of possible suffixes for the resource's MIME type. + +## Methods +ByType +: Returns the page resources of the given type. + +```go +{{ .Resources.ByType "image" }} +``` +Match +: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive. + +```go +{{ .Resources.Match "images/*" }} +``` + +GetMatch +: Same as `Match` but will return the first match. + +### Pattern Matching +```go +// Using Match/GetMatch to find this images/sunset.jpg ? +.Resources.Match "images/sun*" ✅ +.Resources.Match "**/sunset.jpg" ✅ +.Resources.Match "images/*.jpg" ✅ +.Resources.Match "**.jpg" ✅ +.Resources.Match "*" 🚫 +.Resources.Match "sunset.jpg" 🚫 +.Resources.Match "*sunset.jpg" 🚫 + +``` + +## Page Resources Metadata + +The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). + +{{% note %}} +Resources of type `page` get `Title` etc. from their own front matter. +{{% /note %}} + +name +: Sets the value returned in `Name`. + +{{% warning %}} +The methods `Match` and `GetMatch` use `Name` to match the resources. +{{%/ warning %}} + +title +: Sets the value returned in `Title` + +params +: A map of custom key/values. + + +### Resources metadata example + +{{< code-toggle copy="false">}} +title: Application +date : 2018-01-25 +resources : +- src : "images/sunset.jpg" + name : "header" +- src : "documents/photo_specs.pdf" + title : "Photo Specifications" + params: + icon : "photo" +- src : "documents/guide.pdf" + title : "Instruction Guide" +- src : "documents/checklist.pdf" + title : "Document Checklist" +- src : "documents/payment.docx" + title : "Proof of Payment" +- src : "**.pdf" + name : "pdf-file-:counter" + params : + icon : "pdf" +- src : "**.docx" + params : + icon : "word" +{{</ code-toggle >}} + +From the example above: + +- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`. +- `documents/photo_specs.pdf` will get the `photo` icon. +- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`. +- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon. +- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`. +- Every docx in the bundle will receive the `word` icon. + +{{% warning %}} +The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule. +{{%/ warning %}} + +### The `:counter` placeholder in `name` and `title` + +The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`. + +The counter starts at 1 the first time they are used in either `name` or `title`. + +For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as: + +{{< code-toggle copy="false">}} +[[resources]] + src = "*specs.pdf" + title = "Specification #:counter" +[[resources]] + src = "**.pdf" + name = "pdf-file-:counter" +{{</ code-toggle >}} + +the `Name` and `Title` will be assigned to the resource files as follows: + +| Resource file | `Name` | `Title` | +|-------------------|-------------------|-----------------------| +| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` | +| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` | +| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` | +| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` | diff --git a/exampleSite/content/en/documentation/explanation/content-management/related.md b/exampleSite/content/en/documentation/explanation/content-management/related.md new file mode 100644 index 0000000..b4fbe0f --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/related.md @@ -0,0 +1,134 @@ +--- +title: Related Content +description: List related content in "See Also" sections. +date: 2017-09-05 +categories: [content management] +keywords: [content] + +weight: 30 +draft: false +aliases: [/content/related/,/related/] +toc: true +--- + + +Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content). + +## List Related Content + + +To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template: + +{{< code file="layouts/partials/related.html" >}} +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +<h3>See Also</h3> +<ul> + {{ range . }} + <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### Methods + +Here is the list of "Related" methods available on a page collection such `.RegularPages`. + +#### .Related PAGE +Returns a collection of pages related the given one. + +``` +{{ $related := .Site.RegularPages.Related . }} +``` + +#### .RelatedIndices PAGE INDICE1 [INDICE2 ...] +Returns a collection of pages related to a given one restricted to a list of indices. + +``` +{{ $related := .Site.RegularPages.RelatedIndices . "tags" "date" }} +``` + +#### .RelatedTo KEYVALS [KEYVALS2 ...] +Returns a collection of pages related together by a set of indices and their match. + +In order to build those set and pass them as argument, one must use the `keyVals` function where the first argument would be the `indice` and the consecutive ones its potential `matches`. + +``` +{{ $related := .Site.RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} +``` + +{{% note %}} +Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. +{{% /note %}} + +## Configure Related Content +Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed. + +### Default configuration + +Without any `related` configuration set on the project, Hugo's Related Content methods will use the following. + +{{< code-toggle file="config" >}} +related: + threshold: 80 + includeNewer: false + toLower: false + indices: + - name: keywords + weight: 100 + - name: date + weight: 10 +{{< /code-toggle >}} + +Note that if you have configured `tags` as a taxonomy, `tags` will also be added to the default configuration abve with the weight of `80`. + +Custom configuration should be set using the same syntax. + +{{% note %}} +If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults. +{{% /note %}} + +### Top Level Config Options + +threshold +: A value between 0-100. Lower value will give more, but maybe not so relevant, matches. + +includeNewer +: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. + +toLower +: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. + +### Config Options per Index + +name +: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. + +weight +: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. + +pattern +: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. + +toLower +: See above. + +## Performance Considerations + +**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast. + +This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread: + +{{< tweet 898398437527363585 >}} + +Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog. + +He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that: + +* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before. +* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites. + +{{% note %}} +We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). +{{% /note %}} diff --git a/exampleSite/content/en/documentation/explanation/content-management/sections.md b/exampleSite/content/en/documentation/explanation/content-management/sections.md new file mode 100644 index 0000000..6d09986 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/sections.md @@ -0,0 +1,95 @@ +--- +title: Content Sections +linktitle: Sections +description: "Hugo generates a **section tree** that matches your content." +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [content management] +keywords: [lists,sections,content types,organization] + +weight: 50 #rem +draft: false +aliases: [/content/sections/] +toc: true +--- + +A **Section** is a collection of pages that gets defined based on the +organization structure under the `content/` directory. + +By default, all the **first-level** directories under `content/` form their own +sections (**root sections**). + +If a user needs to define a section `foo` at a deeper level, they need to create +a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles] +for more information). + + +{{% note %}} +A **section** cannot be defined or overridden by a front matter parameter -- it +is strictly derived from the content organization structure. +{{% /note %}} + +## Nested Sections + +The sections can be nested as deeply as you need. + +```bash +content +└── blog <-- Section, because first-level dir under content/ + ├── funny-cats + │ ├── mypost.md + │ └── kittens <-- Section, because contains _index.md + │ └── _index.md + └── tech <-- Section, because contains _index.md + └── _index.md +``` + +**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).** + +{{% note %}} +When we talk about a **section** in correlation with template selection, it is +currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`). + +If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter. +{{% /note %}} + +## Example: Breadcrumb Navigation + +With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation: + +{{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}} +<ol class="nav navbar-nav"> + {{ template "breadcrumbnav" (dict "p1" . "p2" .) }} +</ol> +{{ define "breadcrumbnav" }} +{{ if .p1.Parent }} +{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) }} +{{ else if not .p1.IsHome }} +{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }} +{{ end }} +<li{{ if eq .p1 .p2 }} class="active"{{ end }}> + <a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a> +</li> +{{ end }} +{{< /code >}} + +## Section Page Variables and Methods + +Also see [Page Variables](/variables/page/). + +{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}} + +## Content Section Lists + +Hugo will automatically create pages for each *root section* that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered. + +## Content *Section* vs Content *Type* + +By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype][] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`. + +[archetype]: /content-management/archetypes/ +[content type]: /content-management/types/ +[directory structure]: /getting-started/directory-structure/ +[section templates]: /templates/section-templates/ +[branch bundles]: /content-management/page-bundles/#branch-bundles diff --git a/exampleSite/content/en/documentation/explanation/content-management/shortcodes.md b/exampleSite/content/en/documentation/explanation/content-management/shortcodes.md new file mode 100644 index 0000000..3ed8df0 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/shortcodes.md @@ -0,0 +1,443 @@ +--- +title: Shortcodes +linktitle: +description: Shortcodes are simple snippets inside your content files calling built-in or custom templates. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2019-11-07 + +weight: 35 #rem +categories: [content management] +keywords: [markdown,content,shortcodes] +draft: false +aliases: [/extras/shortcodes/] +testparam: "Hugo Rocks!" +toc: true +--- + +## What a Shortcode is + +Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframe>`'s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax. + +Hugo created **shortcodes** to circumvent these limitations. + +A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead. + +In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation. + +## Use Shortcodes + +{{< youtube 2xkNJL4gJ9E >}} + +In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted. + +The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`. + +Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash. + +Here are two examples of paired shortcodes: + +``` +{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}} +``` + +``` +{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}} +``` + +The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second. + +### Shortcodes with raw string parameters + +{{< new-in "0.64.1" >}} + +You can pass multiple lines as parameters to a shortcode by using raw string literals: + +``` +{{</* myshortcode `This is some <b>HTML</b>, +and a new line with a "quoted string".` */>}} +``` + +### Shortcodes with Markdown + +In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer (e.g. Blackfriday for Markdown), meaning they can be part of the generated table of contents, footnotes, etc. + +If you want the old behavior, you can put the following line in the start of your shortcode template: + +``` +{{ $_hugo_config := `{ "version": 1 }` }} +``` + + +### Shortcodes Without Markdown + +The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML: + +``` +{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}} +``` + +### Nested Shortcodes + +You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps]. + +## Use Hugo's Built-in Shortcodes + +Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean. + +### `figure` + +`figure` is an extension of the image syntax in markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement]. + +The `figure` shortcode can use the following named parameters: + +src +: URL of the image to be displayed. + +link +: If the image needs to be hyperlinked, URL of the destination. + +target +: Optional `target` attribute for the URL if `link` parameter is set. + +rel +: Optional `rel` attribute for the URL if `link` parameter is set. + +alt +: Alternate text for the image if the image cannot be displayed. + +title +: Image title. + +caption +: Image caption. Markdown within the value of `caption` will be rendered. + +class +: `class` attribute of the HTML `figure` tag. + +height +: `height` attribute of the image. + +width +: `width` attribute of the image. + +attr +: Image attribution text. Markdown within the value of `attr` will be rendered. + +attrlink +: If the attribution text needs to be hyperlinked, URL of the destination. + +#### Example `figure` Input + +{{< code file="figure-input-example.md" >}} +{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}} +{{< /code >}} + +#### Example `figure` Output + +{{< output file="figure-output-example.html" >}} +<figure> + <img src="/media/spf13.jpg" /> + <figcaption> + <h4>Steve Francia</h4> + </figcaption> +</figure> +{{< /output >}} + +### `gist` + +Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]: + +``` +https://gist.github.com/spf13/7896402 +``` + +We can embed the gist in our content via username and gist ID pulled from the URL: + +``` +{{</* gist spf13 7896402 */>}} +``` + +#### Example `gist` Input + +If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument: + +{{< code file="gist-input.md" >}} +{{</* gist spf13 7896402 "img.html" */>}} +{{< /code >}} + +#### Example `gist` Output + +{{< output file="gist-output.html" >}} +{{< gist spf13 7896402 >}} +{{< /output >}} + +#### Example `gist` Display + +To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. + +{{< gist spf13 7896402 >}} + +### `highlight` + +This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/tools/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode. + +#### Example `highlight` Input + +{{< code file="content/tutorials/learn-html.md" >}} +{{</* highlight html */>}} +<section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Pages }} + {{ .Render "summary"}} + {{ end }} + </div> +</section> +{{</* /highlight */>}} +{{< /code >}} + +#### Example `highlight` Output + +The `highlight` shortcode example above would produce the following HTML when the site is rendered: + +{{< output file="tutorials/learn-html/index.html" >}} +<span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span> + <span style="color: #f92672"><div></span> + <span style="color: #f92672"><h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"title"</span><span style="color: #f92672">></span>{{ .Title }}<span style="color: #f92672"></h1></span> + {{ range .Pages }} + {{ .Render "summary"}} + {{ end }} + <span style="color: #f92672"></div></span> +<span style="color: #f92672"></section></span> +{{< /output >}} + +{{% note "More on Syntax Highlighting" %}} +To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/tools/syntax-highlighting/). +{{% /note %}} + +### `instagram` + +If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL: + +``` +https://www.instagram.com/p/BWNjjyYFxVx/ +``` + +#### Example `instagram` Input + +{{< code file="instagram-input.md" >}} +{{</* instagram BWNjjyYFxVx */>}} +{{< /code >}} + +You also have the option to hide the caption: + +{{< code file="instagram-input-hide-caption.md" >}} +{{</* instagram BWNjjyYFxVx hidecaption */>}} +{{< /code >}} + +#### Example `instagram` Output + +By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup: + +{{< output file="instagram-hide-caption-output.html" >}} +{{< instagram BWNjjyYFxVx hidecaption >}} +{{< /output >}} + +#### Example `instagram` Display + +Using the preceding `instagram` with `hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. + +{{< instagram BWNjjyYFxVx hidecaption >}} + + + +{{% note %}} +The `instagram`-shortcode refers an endpoint of Instagram's API, that's deprecated since October 24th, 2020. Thus, no images can be fetched from this API endpoint, resulting in an error when the `instagram`-shortcode is used. For more information please have a look at GitHub issue [#7879](https://github.com/gohugoio/hugo/issues/7879). +{{% /note %}} + +### `param` + +Gets a value from the current `Page's` params set in front matter, with a fall back to the site param value. It will log an `ERROR` if the param with the given key could not be found in either. + +```bash +{{</* param testparam */>}} +``` + +Since `testparam` is a param defined in front matter of this page with the value `Hugo Rocks!`, the above will print: + +{{< param testparam >}} + +To access deeply nested params, use "dot syntax", e.g: + +```bash +{{</* param "my.nested.param" */>}} +``` + +### `ref` and `relref` + +These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page. + +`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo. + +{{% note "More on Cross References" %}} +Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation. +{{% /note %}} + +`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`. + +#### Example `ref` and `relref` Input + +``` +[Neat]({{</* ref "blog/neat.md" */>}}) +[Who]({{</* relref "about.md#who" */>}}) +``` + +#### Example `ref` and `relref` Output + +Assuming that standard Hugo pretty URLs are turned on. + +``` +<a href="/blog/neat">Neat</a> +<a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a> +``` + +### `tweet` + +You want to include a single tweet into your blog post? Everything you need is the URL of the tweet: + +``` +https://twitter.com/spf13/status/877500564405444608 +``` + +#### Example `tweet` Input + +Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode: + +{{< code file="example-tweet-input.md" >}} +{{</* tweet 877500564405444608 */>}} +{{< /code >}} + +#### Example `tweet` Output + +Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup: + +{{< output file="example-tweet-output.html" >}} +{{< tweet 877500564405444608 >}} +{{< /output >}} + +#### Example `tweet` Display + +Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. + +{{< tweet 877500564405444608 >}} + +### `vimeo` + +Adding a video from [Vimeo][] is equivalent to the [YouTube Input shortcode][]. + +``` +https://vimeo.com/channels/staffpicks/146022717 +``` + +#### Example `vimeo` Input + +Extract the ID from the video's URL and pass it to the `vimeo` shortcode: + +{{< code file="example-vimeo-input.md" >}} +{{</* vimeo 146022717 */>}} +{{< /code >}} + +#### Example `vimeo` Output + +Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup: + +{{< output file="example-vimeo-output.html" >}} +{{< vimeo 146022717 >}} +{{< /output >}} + +{{% tip %}} +If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`. + +``` +{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}} +``` +{{% /tip %}} + +#### Example `vimeo` Display + +Using the preceding `vimeo` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. + +{{< vimeo 146022717 >}} + +### `youtube` + +The `youtube` shortcode embeds a responsive video player for [YouTube videos][]. Only the ID of the video is required, e.g.: + +``` +https://www.youtube.com/watch?v=w7Ft2ymGmfc +``` + + +#### Example `youtube` Input + +Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode: + +{{< code file="example-youtube-input.md" >}} +{{</* youtube w7Ft2ymGmfc */>}} +{{< /code >}} + +Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video id to the parameter `id`: + + +{{< code file="example-youtube-input-with-autoplay.md" >}} +{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}} +{{< /code >}} + +For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used. + +{{< code file="example-youtube-input-with-title.md" >}} +{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}} +{{< /code >}} + + +#### Example `youtube` Output + +Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup: + +{{< code file="example-youtube-output.html" >}} +{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}} +{{< /code >}} + +#### Example `youtube` Display + +Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart]. + +{{< youtube w7Ft2ymGmfc >}} + +## Privacy Config + +To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR][]. + +## Create Custom Shortcodes + +To learn more about creating custom shortcodes, see the [shortcode template documentation][]. + +[`figure` shortcode]: #figure +[contentmanagementsection]: /content-management/formats/ +[examplegist]: https://gist.github.com/spf13/7896402 +[figureelement]: https://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements." +[Hugo and the GDPR]: /about/hugo-and-gdpr/ +[Instagram]: https://www.instagram.com/ +[pagevariables]: /variables/page/ +[partials]: /templates/partials/ +[Pygments]: https://pygments.org/ +[quickstart]: /getting-started/quick-start/ +[sctemps]: /templates/shortcode-templates/ +[scvars]: /variables/shortcodes/ +[shortcode template documentation]: /templates/shortcode-templates/ +[templatessection]: /templates/ +[Vimeo]: https://vimeo.com/ +[YouTube Videos]: https://www.youtube.com/ +[YouTube Input shortcode]: #youtube diff --git a/exampleSite/content/en/documentation/explanation/content-management/static-files.md b/exampleSite/content/en/documentation/explanation/content-management/static-files.md new file mode 100644 index 0000000..996b068 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/static-files.md @@ -0,0 +1,67 @@ +--- +title: Static Files +description: "Files that get served **statically** (as-is, no modification) on the site root." +date: 2017-11-18 +categories: [content management] +keywords: [source, directories] + +weight: 130 #rem +aliases: [/static-files] +toc: true +--- + +By default, the `static/` directory in the site project is used for +all **static files** (e.g. stylesheets, JavaScript, images). The static files are served on the site root path (eg. if you have the file `static/image.png` you can access it using `http://{server-url}/image.png`, to include it in a document you can use ` )`. + +Hugo can be configured to look into a different directory, or even +**multiple directories** for such static files by configuring the +`staticDir` parameter in the [site config][]. All the files in all the +static directories will form a union filesystem. + +This union filesystem will be served from your site root. So a file +`<SITE PROJECT>/static/me.png` will be accessible as +`<MY_BASEURL>/me.png`. + +Here's an example of setting `staticDir` and `staticDir2` for a +multi-language site: + +{{< code-toggle copy="false" file="config" >}} +staticDir = ["static1", "static2"] + +[languages] +[languages.en] +staticDir2 = "static_en" +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" +[languages.no] +staticDir = ["staticDir_override", "static_no"] +baseURL = "https://example.no" +languageName = "Norsk" +weight = 1 +title = "På norsk" +{{</ code-toggle >}} + +In the above, with no theme used: + +- The English site will get its static files as a union of "static1", + "static2" and "static_en". On file duplicates, the right-most + version will win. +- The Norwegian site will get its static files as a union of + "staticDir_override" and "static_no". + +Note 1 +: The **2** (can be a number between 0 and 10) in `staticDir2` is + added to tell Hugo that you want to **add** this directory to the + global set of static directories defined using `staticDir`. Using + `staticDir` on the language level would replace the global value (as + can be seen in the Norwegian site case). + +Note 2 +: The example above is a [multihost setup][]. In a regular setup, all + the static directories will be available to all sites. + + +[site config]: /getting-started/configuration/#all-configuration-settings +[multihost setup]: /content-management/multilingual/#configure-multilingual-multihost diff --git a/exampleSite/content/en/documentation/explanation/content-management/summaries.md b/exampleSite/content/en/documentation/explanation/content-management/summaries.md new file mode 100644 index 0000000..3f9372b --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/summaries.md @@ -0,0 +1,109 @@ +--- +title: Content Summaries +linktitle: Summaries +description: Hugo generates summaries of your content. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-01-10 +categories: [content management] +keywords: [summaries,abstracts,read more] + +weight: 90 #rem +draft: false +aliases: [/content/summaries/,/content-management/content-summaries/] +toc: true +--- + +With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views. + +## Summary Splitting Options + +* Automatic Summary Split +* Manual Summary Split +* Front Matter Summary + +It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables]. + +### Automatic Summary Splitting + +By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/). + +{{% note %}} +You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`. +{{% /note %}} + +{{% note %}} +The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/). +{{% /note %}} + +### Manual Summary Splitting + +Alternatively, you may add the <code><!--more--></code> summary divider where you want to split the article. + +For [Org mode content][org], use `# more` where you want to split the article. + +Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact. + +{{% note "Summary Divider"%}} +The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature. +{{% /note %}} + +Pros +: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved. + +Cons +: Extra work for content authors, since they need to remember to type <code><!--more--></code> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/). + +{{% warning "Be Precise with the Summary Divider" %}} +Be careful to enter <code><!--more--></code> exactly; i.e., all lowercase and with no whitespace. +{{% /warning %}} + +### Front Matter Summary + +You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter. + +Pros +: Complete freedom of text independent of the content of the article. Markup can be used within the summary. + +Cons +: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article. + +## Summary Selection Order + +Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows: + +1. If there is a <code><!--more--></code> summary divider present in the article the text up to the divider will be provided as per the manual summary split method +2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method +3. The text at the start of the article will be provided as per the automatic summary split method + +{{% warning "Competing selections" %}} +Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a <code><!--more--></code> summary divider Hugo will use the manual summary split method. +{{% /warning %}} + +## Example: First 10 Articles with Summaries + +You can show content summaries with the following code. You could use the following snippet, for example, in a [section template][]. + +{{< code file="page-list-with-summaries.html" >}} +{{ range first 10 .Pages }} + <article> + <!-- this <div> includes the title summary --> + <div> + <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> + {{ .Summary }} + </div> + {{ if .Truncated }} + <!-- This <div> includes a read more link, but only if the summary is truncated... --> + <div> + <a href="{{ .RelPermalink }}">Read More…</a> + </div> + {{ end }} + </article> +{{ end }} +{{< /code >}} + +Note how the `.Truncated` boolean variable value may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article. + +[org]: /content-management/formats/ +[pagevariables]: /variables/page/ +[section template]: /templates/section-templates/ diff --git a/exampleSite/content/en/documentation/explanation/content-management/syntax-highlighting.md b/exampleSite/content/en/documentation/explanation/content-management/syntax-highlighting.md new file mode 100644 index 0000000..830dfb9 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/syntax-highlighting.md @@ -0,0 +1,135 @@ +--- +title: Syntax Highlighting +description: Hugo comes with really fast syntax highlighting from Chroma. +date: 2017-02-01 +publishdate: 2017-02-01 +keywords: [highlighting,chroma,code blocks,syntax] +categories: [content management] + +weight: 20 +sections_weight: 20 +draft: false +aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/] +toc: true +--- + +Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments we used before. + +## Configure Syntax Highlighter + +See [Configure Highlight](/getting-started/configuration-markup#highlight). + +## Generate Syntax Highlighter CSS + +If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet. + +You can generate one with Hugo: + +```bash +hugo gen chromastyles --style=monokai > syntax.css +``` + +Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles. + +## Highlight Shortcode + +Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting. + +Options: + +* `linenos`: configure line numbers. Valid values are `true`, `false`, `table`, or `inline`. `false` will turn off line numbers if it's configured to be on in site config. {{< new-in "0.60.0" >}} `table` will give copy-and-paste friendly code blocks. +* `hl_lines`: lists a set of line numbers or line number ranges to be highlighted. +* `linenostart=199`: starts the line number count from 199. +* `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`; +* `lineanchors`: Configure a prefix for the anchors on line numbers. Will be suffixed with `-`, so linking to the line number 1 with the option `lineanchors=prefix` adds the anchor `prefix-1` to the page. + +### Example: Highlight Shortcode + +``` +{{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}} +// ... code +{{</* / highlight */>}} +``` + +Gives this: + +{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}} +// GetTitleFunc returns a func that can be used to transform a string to +// title case. +// +// The supported styles are +// +// - "Go" (strings.Title) +// - "AP" (see https://www.apstylebook.com/) +// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html) +// +// If an unknown or empty style is provided, AP style is what you get. +func GetTitleFunc(style string) func(s string) string { + switch strings.ToLower(style) { + case "go": + return strings.Title + case "chicago": + return transform.NewTitleConverter(transform.ChicagoStyle) + default: + return transform.NewTitleConverter(transform.APStyle) + } +} +{{< / highlight >}} + +## Highlight Template Func + +See [Highlight](/functions/highlight/). + +## Highlighting in Code Fences + +Highlighting in code fences is enabled by default.{{< new-in "0.60.0" >}} + +```` +```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199} +// ... code +``` +```` + + +Gives this: + +```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199} +// GetTitleFunc returns a func that can be used to transform a string to +// title case. +// +// The supported styles are +// +// - "Go" (strings.Title) +// - "AP" (see https://www.apstylebook.com/) +// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html) +// +// If an unknown or empty style is provided, AP style is what you get. +func GetTitleFunc(style string) func(s string) string { + switch strings.ToLower(style) { + case "go": + return strings.Title + case "chicago": + return transform.NewTitleConverter(transform.ChicagoStyle) + default: + return transform.NewTitleConverter(transform.APStyle) + } +} +``` + +{{< new-in "0.60.0" >}}Note that only Goldmark supports passing attributes such as `hl_lines`, and it's important that it does not contain any spaces. See [goldmark-highlighting](https://github.com/yuin/goldmark-highlighting) for more information. + +The options are the same as in the [highlighting shortcode](/content-management/syntax-highlighting/#highlight-shortcode),including `linenos=false`, but note the slightly different Markdown attribute syntax. + +## List of Chroma Highlighting Languages + +The full list of Chroma lexers and their aliases (which is the identifier used in the `highlight` template func or when doing highlighting in code fences): + +{{< chroma-lexers >}} + +[Prism]: https://prismjs.com +[prismdownload]: https://prismjs.com/download.html +[Highlight.js]: https://highlightjs.org/ +[Rainbow]: https://craig.is/making/rainbows +[Syntax Highlighter]: https://alexgorbatchev.com/SyntaxHighlighter/ +[Google Prettify]: https://github.com/google/code-prettify +[Yandex]: https://yandex.ru/ diff --git a/exampleSite/content/en/documentation/explanation/content-management/taxonomies.md b/exampleSite/content/en/documentation/explanation/content-management/taxonomies.md new file mode 100644 index 0000000..61912a8 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/taxonomies.md @@ -0,0 +1,212 @@ +--- +title: Taxonomies +linktitle: +description: Hugo includes support for user-defined taxonomies. +date: 2017-02-01 +publishdate: 2017-02-01 +keywords: [taxonomies,metadata,front matter,terms] +categories: [content management] + +weight: 80 #rem +draft: false +aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes] +toc: true +--- + +## What is a Taxonomy? + +Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content. + +### Definitions + +Taxonomy +: a categorization that can be used to classify content + +Term +: a key within the taxonomy + +Value +: a piece of content assigned to a term + + +## Example Taxonomy: Movie Website + +Let's assume you are making a website about movies. You may want to include the following taxonomies: + +* Actors +* Directors +* Studios +* Genre +* Year +* Awards + +Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter][] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award. + +### Movie Taxonomy Organization + +To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy: + +``` +Actor <- Taxonomy + Bruce Willis <- Term + The Sixth Sense <- Value + Unbreakable <- Value + Moonrise Kingdom <- Value + Samuel L. Jackson <- Term + Unbreakable <- Value + The Avengers <- Value + xXx <- Value +``` + +From the perspective of the content, the relationships would appear differently, although the data and labels used are the same: + +``` +Unbreakable <- Value + Actors <- Taxonomy + Bruce Willis <- Term + Samuel L. Jackson <- Term + Director <- Taxonomy + M. Night Shyamalan <- Term + ... +Moonrise Kingdom <- Value + Actors <- Taxonomy + Bruce Willis <- Term + Bill Murray <- Term + Director <- Taxonomy + Wes Anderson <- Term + ... +``` + +## Hugo Taxonomy Defaults {#default-taxonomies} + +Hugo natively supports taxonomies. + +Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configuring-taxonomies) as below: + +{{< code-toggle copy="false" >}} +[taxonomies] + tag = "tags" + category = "categories" +{{</ code-toggle >}} + +If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site config][config] to the following: + +{{< code-toggle copy="false" >}} +disableKinds = ["taxonomy","term"] +{{</ code-toggle >}} + +{{< new-in "0.73.0" >}} We have fixed the before confusing page kinds used for taxonomies (see the listing below) to be in line with the terms used when we talk about taxonomies. We have been careful to avoid site breakage, and you should get an ERROR in the console if you need to adjust your `disableKinds` section. + +{{% page-kinds %}} + +### Default Destinations + +When taxonomies are used---and [taxonomy templates][] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages: + +* A single page at `example.com/categories/` that lists all the [terms within the taxonomy][] +* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][] + +## Configure Taxonomies + +Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site config][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML. + +### Example: Adding a custom taxonomy named "series" + +{{% note %}} +While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_. +{{% /note %}} + +{{< code-toggle copy="false" >}} +[taxonomies] + tag = "tags" + category = "categories" + series = "series" +{{</ code-toggle >}} + +### Example: Removing default taxonomies + +If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site config][config]. + +{{< code-toggle copy="false" >}} +[taxonomies] + tag = "tags" +{{</ code-toggle >}} + +If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies). + +{{% note %}} +You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose. + +Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not. +{{% /note %}} + +{{% warning %}} +The configuration option `preserveTaxonomyNames` was removed in Hugo 0.55. + +You can now use `.Page.Title` on the relevant taxonomy node to get the original value. +{{% /warning %}} + +## Add Taxonomies to Content + +Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type][] or [content section][]. + +Assigning content to a taxonomy is done in the [front matter][]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type. + +{{% note %}} +If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/). +{{% /note %}} + +### Example: Front Matter with Taxonomies + +{{< code-toggle copy="false">}} +title = "Hugo: A fast and flexible static site generator" +tags = [ "Development", "Go", "fast", "Blogging" ] +categories = [ "Development" ] +series = [ "Go Web Dev" ] +slug = "hugo" +project_url = "https://github.com/gohugoio/hugo" +{{</ code-toggle >}} + +## Order Taxonomies + +A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates][] and is declared in a content file's [front matter][]. The convention for declaring taxonomic weight is `taxonomyname_weight`. + +The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page. + +### Example: Taxonomic `weight` + +{{< code-toggle copy="false" >}} +title = "foo" +tags = [ "a", "b", "c" ] +tags_weight = 22 +categories = ["d"] +categories_weight = 44 +{{</ code-toggle >}} + +By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies. + +{{% note "Limits to Ordering Taxonomies" %}} +Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight-date). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/). +{{% /note %}} + +## Add custom metadata to a Taxonomy or Term + +If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter. Continuing with our 'Actors' example, let's say you want to add a Wikipedia page link to each actor. Your terms pages would be something like this: + +{{< code file="/content/actors/bruce-willis/_index.md" >}} +--- +title: "Bruce Willis" +wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis" +--- +{{< /code >}} + + +[`urlize` template function]: /functions/urlize/ +[content section]: /content-management/sections/ +[content type]: /content-management/types/ +[documentation on archetypes]: /content-management/archetypes/ +[front matter]: /content-management/front-matter/ +[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-page-templates +[taxonomy templates]: /templates/taxonomy-templates/ +[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates "See how to order terms associated with a taxonomy" +[config]: /getting-started/configuration/ diff --git a/exampleSite/content/en/documentation/explanation/content-management/toc.md b/exampleSite/content/en/documentation/explanation/content-management/toc.md new file mode 100644 index 0000000..cad1e47 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/toc.md @@ -0,0 +1,122 @@ +--- +title: Table of Contents +linktitle: +description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [content management] +keywords: [table of contents, toc] + +weight: 130 #rem +draft: false +aliases: [/extras/toc/] +toc: true +--- + +{{% note "TOC Heading Levels are Fixed" %}} + +Previously, there was no out-of-the-box way to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` was going to start at `<h1>` when pulling from `{{.Content}}`. + +Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a switch to [Goldmark](https://github.com/yuin/goldmark/) as the default library for Markdown which has improved and configurable implementation of TOC. Take a look at [how to configure TOC](/getting-started/configuration-markup/#table-of-contents) for Goldmark renderer. + +{{% /note %}} + +## Usage + +Create your markdown the way you normally would with the appropriate headings. Here is some example content: + +``` +<!-- Your front matter up here --> + +## Introduction + +One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin. + +## My Heading + +He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment. + +### My Subheading + +A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops +``` + +Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`. + +The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC. + +{{% note "Table of contents not available for MMark" %}} +Hugo documents created in the [MMark](/content-management/formats/#mmark) Markdown dialect do not currently display TOCs. TOCs are, however, compatible with all other supported Markdown formats. +{{% /note %}} + +## Template Example: Basic TOC + +The following is an example of a very basic [single page template][]: + +{{< code file="layout/_default/single.html" download="single.html" >}} +{{ define "main" }} +<main> + <article> + <header> + <h1>{{ .Title }}</h1> + </header> + {{ .Content }} + </article> + <aside> + {{ .TableOfContents }} + </aside> +</main> +{{ end }} +{{< /code >}} + +## Template Example: TOC Partial + +The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter][] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals][] in your templating: + +{{< code file="layouts/partials/toc.html" download="toc.html" >}} +{{ if and (gt .WordCount 400 ) (.Params.toc) }} +<aside> + <header> + <h2>{{.Title}}</h2> + </header> + {{.TableOfContents}} +</aside> +{{ end }} +{{< /code >}} + +{{% note %}} +With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{.TableOfContents}}` variable to pull from. +{{% /note %}} + +## Usage with AsciiDoc + +Hugo supports table of contents with AsciiDoc content format. + +In the header of your content file, specify the AsciiDoc TOC directives necessary to ensure that the table of contents is generated. Hugo will use the generated TOC to populate the page variable `.TableOfContents` in the same way as described for Markdown. See example below: + +```asciidoc +// <!-- Your front matter up here --> +:toc: +// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key +:toclevels: 4 + +== Introduction + +One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin. + +== My Heading + +He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment. + +=== My Subheading + +A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops +``` +Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown. + +[conditionals]: /templates/introduction/#conditionals +[front matter]: /content-management/front-matter/ +[pagevars]: /variables/page/ +[partials]: /templates/partials/ +[single page template]: /templates/single-page-templates/ diff --git a/exampleSite/content/en/documentation/explanation/content-management/types.md b/exampleSite/content/en/documentation/explanation/content-management/types.md new file mode 100644 index 0000000..99d00fb --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/types.md @@ -0,0 +1,21 @@ +--- +title: Content Types +description: Hugo is built around content organized in sections. +date: 2017-02-01 +categories: [content management] +keywords: [lists,sections,content types,types,organization] + +weight: 60 #rem +draft: false +aliases: [/content/types] +toc: true +--- + +A **content type** is a way to organize your content. Hugo resolves the content type from either the `type` in front matter or, if not set, the first directory in the file path. E.g. `content/blog/my-first-event.md` will be of type `blog` if no `type` set. + +A content type is used to + +* Determine how the content is rendered. See [Template Lookup Order](/templates/lookup-order/) and [Content Views](https://gohugo.io/templates/views) for more. +* Determine which [archetype](/content-management/archetypes/) template to use for new content. + + diff --git a/exampleSite/content/en/documentation/explanation/content-management/urls.md b/exampleSite/content/en/documentation/explanation/content-management/urls.md new file mode 100644 index 0000000..e000a68 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/content-management/urls.md @@ -0,0 +1,310 @@ +--- +title: URL Management +linktitle: URL Management +description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-09 +keywords: [aliases,redirects,permalinks,urls] +categories: [content management] + +weight: 110 #rem +draft: false +aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/] +toc: true +--- + +## Permalinks + +The default Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishDir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy. + +The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option. + +{{% note "Default Publish and Content Folders" %}} +These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/). +{{% /note %}} + +For example, if one of your [sections][] is called `posts` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively. + +### Permalinks Configuration Example + +{{< code-toggle file="config" copy="false" >}} +permalinks: + posts: /:year/:month/:title/ +{{< /code-toggle >}} + +Only the content under `posts/` will have the new URL structure. For example, the file `content/posts/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`. + +To configure the `permalinks` option for pages in the "root" section, use **/** as the key: + +{{< code-toggle file="config" copy="false" >}} +permalinks: + /: /:year/:month/:filename/ +{{< /code-toggle >}} + +If the standard date-based permalink configuration does not meet your needs, you can also format URL segments using [Go time formatting directives](https://golang.org/pkg/time/#Time.Format). For example, a URL structure with two digit years and month and day digits without zero padding can be accomplished with: + +{{< code-toggle file="config" copy="false" >}} +permalinks: + posts: /:06/:1/:2/:title/ +{{< /code-toggle >}} + +You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`. + +### Permalink Configuration Values + +The following is a list of values that can be used in a `permalink` definition in your site `config` file. All references to time are dependent on the content's date. + +`:year` +: the 4-digit year + +`:month` +: the 2-digit month + +`:monthname` +: the name of the month + +`:day` +: the 2-digit day + +`:weekday` +: the 1-digit day of the week (Sunday = 0) + +`:weekdayname` +: the name of the day of the week + +`:yearday` +: the 1- to 3-digit day of the year + +`:section` +: the content's section + +`:sections` +: the content's sections hierarchy + +`:title` +: the content's title + +`:slug` +: the content's slug (or title if no slug is provided in the front matter) + +`:filename` +: the content's filename (without extension) + +Additionally, a Go time format string prefixed with `:` may be used. + +## Aliases + +Aliases can be used to create redirects to your page from other URLs. + +Aliases comes in two forms: + +1. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/` +2. They are relative to the `Page` they're defined in, e.g. `my-blogpost` or even something like `../blog/my-blogpost` (new in Hugo 0.55). + +### Example: Aliases + +Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this field in TOML and YAML front matter, respectively. + +#### TOML Front Matter + +{{< code file="content/posts/my-awesome-post.md" copy="false" >}} ++++ +aliases = [ + "/posts/my-original-url/", + "/2010/01/01/even-earlier-url.html" +] ++++ +{{< /code >}} + +#### YAML Front Matter + +{{< code file="content/posts/my-awesome-post.md" copy="false" >}} +--- +aliases: + - /posts/my-original-url/ + - /2010/01/01/even-earlier-url.html +--- +{{< /code >}} + +Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-post/`. + +### Example: Aliases in Multilingual + +On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code. + +In `/posts/my-new-post.es.md`: + +``` +--- +aliases: + - /es/posts/my-original-post/ +--- +``` + +From Hugo 0.55 you can also have page-relative aliases, so ` /es/posts/my-original-post/` can be simplified to the more portable `my-original-post/` + +### How Hugo Aliases Work + +When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target. + +For example, a content file at `posts/my-intended-url.md` with the following in the front matter: + +``` +--- +title: My New post +aliases: [/posts/my-old-url/] +--- +``` + +Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/` will contain the following: + +``` +<!DOCTYPE html> +<html> + <head> + <title>https://example.com/posts/my-intended-url</title> + <link rel="canonical" href="https://example.com/posts/my-intended-url"/> + <meta name="robots" content="noindex"> + <meta http-equiv="content-type" content="text/html; charset=utf-8"/> + <meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/> + </head> +</html> +``` + +The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name="robots" content="noindex">` lets search engine bots know that they should not crawl and index your new alias page. + +### Customize +You may customize this alias page by creating an `alias.html` template in the +layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is + +`Permalink` +: the link to the page being aliased + +`Page` +: the Page data for the page being aliased + +### Important Behaviors of Aliases + +1. Hugo makes no assumptions about aliases. They also do not change based +on your UglyURLs setting. You need to provide absolute paths to your web root +and the complete filename or directory. +2. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location. + +## Pretty URLs + +Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work. + +The following demonstrates the concept: + +``` +content/posts/_index.md +=> example.com/posts/index.html +content/posts/post-1.md +=> example.com/posts/post-1/ +``` + +## Ugly URLs + +If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also set the `HUGO_UGLYURLS` environment variable to `true` when running `hugo` or `hugo server`. + +If you want a specific piece of content to have an exact URL, you can specify this in the [front matter][] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior. + +See [Content Organization][contentorg] for more details on paths. + +``` +. +└── content + └── about + | └── _index.md // <- https://example.com/about/ + ├── posts + | ├── firstpost.md // <- https://example.com/posts/firstpost/ + | ├── happy + | | └── ness.md // <- https://example.com/posts/happy/ness/ + | └── secondpost.md // <- https://example.com/posts/secondpost/ + └── quote + ├── first.md // <- https://example.com/quote/first/ + └── second.md // <- https://example.com/quote/second/ +``` + +Here's the same organization run with `hugo --uglyURLs`: + +``` +. +└── content + └── about + | └── _index.md // <- https://example.com/about.html + ├── posts + | ├── firstpost.md // <- https://example.com/posts/firstpost.html + | ├── happy + | | └── ness.md // <- https://example.com/posts/happy/ness.html + | └── secondpost.md // <- https://example.com/posts/secondpost.html + └── quote + ├── first.md // <- https://example.com/quote/first.html + └── second.md // <- https://example.com/quote/second.html +``` + + +## Canonicalization + +By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`. + +By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://example.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `https://example.com/css/foo.css`. + +Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue. + +Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved. + +{{% note "`canonifyURLs` default change" %}} +In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions. +{{% /note %}} + +To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13. + +``` +hugo config | grep -i canon +``` + +Or, if you are on Windows and do not have `grep` installed: + +``` +hugo config | FINDSTR /I canon +``` + +## Set URL in Front Matter + +In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content. + +Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg]. + +From Hugo 0.55, you can use URLs relative to the current site context (the language), which makes it simpler to maintain. For a Japanese translation, both of the following examples would get the same URL: + +```markdown +--- +title: "Custom URL!" +url: "/jp/custom/foo" +--- +``` + +```markdown +--- +title: "Custom URL!" +url: "custom/foo" +--- +``` + + +## Relative URLs + +By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system. + +Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content. + +For example, if your `/posts/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`. + +[config]: /getting-started/configuration/ +[contentorg]: /content-management/organization/ +[front matter]: /content-management/front-matter/ +[multilingual]: /content-management/multilingual/ +[sections]: /content-management/sections/ +[usage]: /getting-started/usage/ diff --git a/exampleSite/content/en/documentation/explanation/refexamples/_index.md b/exampleSite/content/en/documentation/explanation/refexamples/_index.md new file mode 100644 index 0000000..438613e --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/refexamples/_index.md @@ -0,0 +1,3 @@ +--- +title: Ref Examples +--- diff --git a/exampleSite/content/en/documentation/explanation/refexamples/multiplication-explained.md b/exampleSite/content/en/documentation/explanation/refexamples/multiplication-explained.md new file mode 100644 index 0000000..700c4b5 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/refexamples/multiplication-explained.md @@ -0,0 +1,6 @@ +--- +title: How to do math in Hugo +keywords: ["math", "algebra"] +--- + +In math, to multiply means to add equal groups. When we multiply, the number of things in the group increases. The two factors and the product are parts of a multiplication problem. In the multiplication problem, 6 × 9 = 54, the numbers 6 and 9 are the factors, while the number 54 is the product.
\ No newline at end of file diff --git a/exampleSite/content/en/documentation/explanation/templates/404.md b/exampleSite/content/en/documentation/explanation/templates/404.md new file mode 100644 index 0000000..cd56458 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/404.md @@ -0,0 +1,61 @@ +--- +title: Custom 404 Page +linktitle: 404 Page +description: If you know how to create a single page template, you have unlimited options for creating a custom 404. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-31 +categories: [templates] +keywords: [404, page not found] + +weight: 120 #rem +draft: false +aliases: [] +toc: false +--- + +When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) by creating a 404.html template file in your `/layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root. + +404 pages will have all the regular [page variables][pagevars] available to use in the templates. + +In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`. + +``` +▾ layouts/ + 404.html +``` + +## 404.html + +This is a basic example of a 404.html template: + +{{< code file="layouts/404.html" download="404.html" >}} +{{ define "main"}} + <main id="main"> + <div> + <h1 id="title"><a href="{{ "/" | relURL }}">Go Home</a></h1> + </div> + </main> +{{ end }} +{{< /code >}} + +## Automatic Loading + +Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example: + +* [GitHub Pages](/hosting-and-deployment/hosting-on-github/) and [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/). The 404 page is automatic. +* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site. +* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. +* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI. +* Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html) +* Caddy Server. Using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors) +* Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404) +* Azure Static website. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [More details are available in the Static website documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website). + +{{% note %}} +`hugo server` will not automatically load your custom `404.html` file, but you +can test the appearance of your custom "not found" page by navigating your +browser to `/404.html`. +{{% /note %}} + +[pagevars]: /variables/page/ diff --git a/exampleSite/content/en/documentation/explanation/templates/_index.md b/exampleSite/content/en/documentation/explanation/templates/_index.md new file mode 100644 index 0000000..d16b2c2 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/_index.md @@ -0,0 +1,16 @@ +--- +title: Templates +linktitle: Templates +description: Go templating, template types and lookup order, shortcodes, and data. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 + +weight: 01 #rem +categories: [templates] +keywords: [] +draft: false +aliases: [/templates/overview/,/templates/content] +toc: false +notesforauthors: +--- diff --git a/exampleSite/content/en/documentation/explanation/templates/alternatives.md b/exampleSite/content/en/documentation/explanation/templates/alternatives.md new file mode 100644 index 0000000..22dbb38 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/alternatives.md @@ -0,0 +1,19 @@ +--- +title: DEPRECATED - Alternative Templating Languages +linktitle: Alternative Templating +description: DEPRECATED - Support for Ace & Amber templating has been removed in version 0.62 +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-20 +categories: [templates] +keywords: [amber,ace,templating languages] + +weight: 170 +sections_weight: 170 +draft: false +aliases: [/templates/ace/,/templates/amber/] +toc: true +--- + +Support for Amber and Ace templates has been removed since Hugo 0.62 per [issue #6609](https://github.com/gohugoio/hugo/issues/6609). diff --git a/exampleSite/content/en/documentation/explanation/templates/base.md b/exampleSite/content/en/documentation/explanation/templates/base.md new file mode 100644 index 0000000..4eb404d --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/base.md @@ -0,0 +1,101 @@ +--- +title: Base Templates and Blocks +linktitle: +description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page). +godocref: https://golang.org/pkg/text/template/#example_Template_block +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates,fundamentals] +keywords: [blocks,base] + +weight: 20 +sections_weight: 20 +draft: false +aliases: [/templates/blocks/,/templates/base-templates-and-blocks/] +toc: true +--- + +The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary. + +{{< youtube QVOMCYitLEc >}} + +## Base Template Lookup Order + +{{< new-in "0.63.0" >}} Since Hugo v0.63, the base template lookup order closely follows that of the template it applies to (e.g. `_default/list.html`). + +See [Template Lookup Order](/templates/lookup-order/) for details and examples. + +## Define the Base Template + +The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order. + +{{< code file="layouts/_default/baseof.html" download="baseof.html" >}} +<!DOCTYPE html> +<html> + <head> + <meta charset="utf-8"> + <title>{{ block "title" . }} + <!-- Blocks may include default content. --> + {{ .Site.Title }} + {{ end }}</title> + </head> + <body> + <!-- Code that all your templates share, like a header --> + {{ block "main" . }} + <!-- The part of the page that begins to differ between templates --> + {{ end }} + {{ block "footer" . }} + <!-- More shared code, perhaps a footer but that can be overridden if need be in --> + {{ end }} + </body> +</html> +{{< /code >}} + +## Override the Base Template + +From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from: + +{{< code file="layouts/_default/list.html" download="list.html" >}} +{{ define "main" }} + <h1>Posts</h1> + {{ range .Pages }} + <article> + <h2>{{ .Title }}</h2> + {{ .Content }} + </article> + {{ end }} +{{ end }} +{{< /code >}} + +This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists. + +{{% warning %}} +Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example: + +``` +<!-- Seemingly harmless HTML comment..that will break your layout at build --> +{{ define "main" }} +...your code here +{{ end }} +``` +[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6) +{{% /warning %}} + +The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]: + +{{< code file="layouts/_default/single.html" download="single.html" >}} +{{ define "title" }} + <!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example--> + {{ .Title }} – {{ .Site.Title }} +{{ end }} +{{ define "main" }} + <h1>{{ .Title }}</h1> + {{ .Content }} +{{ end }} +{{< /code >}} + +[hugolists]: /templates/lists +[lookup]: /templates/lookup-order/ +[rendering the section]: /templates/section-templates/ +[singletemplate]: /templates/single-page-templates/ diff --git a/exampleSite/content/en/documentation/explanation/templates/data-templates.md b/exampleSite/content/en/documentation/explanation/templates/data-templates.md new file mode 100644 index 0000000..ebcbae8 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/data-templates.md @@ -0,0 +1,256 @@ +--- +title: Data Templates +linktitle: +description: In addition to Hugo's built-in variables, you can specify your own custom data in templates or shortcodes that pull from both local and dynamic sources. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-12 +categories: [templates] +keywords: [data,dynamic,csv,json,toml,yaml] + +weight: 80 +sections_weight: 80 +draft: false +aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/] +toc: true +--- + +<!-- begin data files --> + +Hugo supports loading data from YAML, JSON, and TOML files located in the `data` directory in the root of your Hugo project. + +{{< youtube FyPgSuwIMWQ >}} + +## The Data Folder + +The `data` folder is where you can store additional data for Hugo to use when generating your site. Data files aren't used to generate standalone pages; rather, they're meant to be supplemental to content files. This feature can extend the content in case your front matter fields grow out of control. Or perhaps you want to show a larger dataset in a template (see example below). In both cases, it's a good idea to outsource the data in their own files. + +These files must be YAML, JSON, or TOML files (using the `.yml`, `.yaml`, `.json`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable. + +## Data Files in Themes + +Data Files can also be used in [Hugo themes][themes] but note that theme data files follow the same logic as other template files in the [Hugo lookup order][lookup] (i.e., given two files with the same name and relative path, the file in the root project `data` directory will override the file in the `themes/<THEME>/data` directory). + +Therefore, theme authors should take care to not include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. For theme-specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace; e.g. `mytheme/data/<THEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag. + +The keys in the map created with data templates from data files will be a dot-chained set of `path`, `filename`, and `key` in file (if applicable). + +This is best explained with an example: + +## Example: Jaco Pastorius' Solo Discography + +[Jaco Pastorius](https://en.wikipedia.org/wiki/Jaco_Pastorius_discography) was a great bass player, but his solo discography is short enough to use as an example. [John Patitucci](https://en.wikipedia.org/wiki/John_Patitucci) is another bass giant. + +The example below is a bit contrived, but it illustrates the flexibility of data Files. This example uses TOML as its file format with the two following data files: + +* `data/jazz/bass/jacopastorius.toml` +* `data/jazz/bass/johnpatitucci.toml` + +`jacopastorius.toml` contains the content below. `johnpatitucci.toml` contains a similar list: + +``` +discography = [ +"1974 – Modern American Music … Period! The Criteria Sessions", +"1974 – Jaco", +"1976 - Jaco Pastorius", +"1981 - Word of Mouth", +"1981 - The Birthday Concert (released in 1995)", +"1982 - Twins I & II (released in 1999)", +"1983 - Invitation", +"1986 - Broadway Blues (released in 1998)", +"1986 - Honestly Solo Live (released in 1990)", +"1986 - Live In Italy (released in 1991)", +"1986 - Heavy'n Jazz (released in 1992)", +"1991 - Live In New York City, Volumes 1-7.", +"1999 - Rare Collection (compilation)", +"2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)", +"2007 - The Essential Jaco Pastorius (compilation)" +] +``` + +The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single bass player by adding the filename without the suffix, e.g. `.Site.Data.jazz.bass.jacopastorius`. + +You can now render the list of recordings for all the bass players in a template: + +``` +{{ range $.Site.Data.jazz.bass }} + {{ partial "artist.html" . }} +{{ end }} +``` + +And then in the `partials/artist.html`: + +``` +<ul> +{{ range .discography }} + <li>{{ . }}</li> +{{ end }} +</ul> +``` + +Discover a new favorite bass player? Just add another `.toml` file in the same directory. + +## Example: Accessing Named Values in a Data File + +Assume you have the following data structure in your `User0123.[yml|toml|json]` data file located directly in `data/`: + +{{< code-toggle file="User0123" >}} +Name: User0123 +"Short Description": "He is a **jolly good** fellow." +Achievements: + - "Can create a Key, Value list from Data File" + - "Learns Hugo" + - "Reads documentation" +{{</ code-toggle >}} + +You can use the following code to render the `Short Description` in your layout:: + +``` +<div>Short Description of {{.Site.Data.User0123.Name}}: <p>{{ index .Site.Data.User0123 "Short Description" | markdownify }}</p></div> +``` + +Note the use of the [`markdownify` template function][markdownify]. This will send the description through the Blackfriday Markdown rendering engine. + +<!-- begin "Data-drive Content" page --> + +## Data-Driven Content + +In addition to the [data files](/extras/datafiles/) feature, Hugo also has a "data-driven content" feature, which lets you load any [JSON](https://www.json.org/) or [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) file from nearly any resource. + +Data-driven content currently consists of two functions, `getJSON` and `getCSV`, which are available in all template files. + +## Implementation details + +### Call the Functions with a URL + +In your template, call the functions like this: + +``` +{{ $dataJ := getJSON "url" }} +{{ $dataC := getCSV "separator" "url" }} +``` + +If you use a prefix or postfix for the URL, the functions accept [variadic arguments][variadic]: + +``` +{{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }} +{{ $dataC := getCSV "separator" "url prefix" "arg1" "arg2" "arg n" }} +``` + +The separator for `getCSV` must be put in the first position and can only be one character long. + +All passed arguments will be joined to the final URL: + +``` +{{ $urlPre := "https://api.github.com" }} +{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} +``` + +This will resolve internally to the following: + +``` +{{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }} +``` + +Finally, you can range over an array. This example will output the +first 5 gists for a GitHub user: + +``` +<ul> + {{ $urlPre := "https://api.github.com" }} + {{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} + {{ range first 5 $gistJ }} + {{ if .public }} + <li><a href="{{ .html_url }}" target="_blank">{{ .description }}</a></li> + {{ end }} + {{ end }} +</ul> +``` + +### Example for CSV files + +For `getCSV`, the one-character-long separator must be placed in the first position followed by the URL. The following is an example of creating an HTML table in a [partial template][partials] from a published CSV: + +{{< code file="layouts/partials/get-csv.html" >}} + <table> + <thead> + <tr> + <th>Name</th> + <th>Position</th> + <th>Salary</th> + </tr> + </thead> + <tbody> + {{ $url := "https://example.com/finance/employee-salaries.csv" }} + {{ $sep := "," }} + {{ range $i, $r := getCSV $sep $url }} + <tr> + <td>{{ index $r 0 }}</td> + <td>{{ index $r 1 }}</td> + <td>{{ index $r 2 }}</td> + </tr> + {{ end }} + </tbody> + </table> +{{< /code >}} + +The expression `{{index $r number}}` must be used to output the nth-column from the current row. + +### Cache URLs + +Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache/`. The variable `$TMPDIR` will be resolved to your system-dependent temporary directory. + +With the command-line flag `--cacheDir`, you can specify any folder on your system as a caching directory. + +You can also set `cacheDir` in the [main configuration file][config]. + +If you don't like caching at all, you can fully disable caching with the command line flag `--ignoreCache`. + +### Authentication When Using REST URLs + +Currently, you can only use those authentication methods that can be put into an URL. [OAuth][] and other authentication methods are not implemented. + +## Load Local files + +To load local files with `getJSON` and `getCSV`, the source files must reside within Hugo's working directory. The file extension does not matter, but the content does. + +It applies the same output logic as above in [Call the Functions with a URL](#call-the-functions-with-a-url). + +{{% note %}} +The local CSV files to be loaded using `getCSV` must be located **outside** of the `data` directory. +{{% /note %}} + +## LiveReload with Data Files + +There is no chance to trigger a [LiveReload][] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes/<THEME>/data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading of data takes a while, Hugo stops processing your Markdown files until the data download has completed. + +{{% warning "URL Data and LiveReload" %}} +If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly. +{{% /warning %}} + +## Examples of Data-driven Content + +- Photo gallery JSON powered: [https://github.com/pcdummy/hugo-lightslider-example](https://github.com/pcdummy/hugo-lightslider-example) +- GitHub Starred Repositories [in a post](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) using data-driven content in a [custom short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html). + +## Specs for Data Formats + +* [TOML Spec][toml] +* [YAML Spec][yaml] +* [JSON Spec][json] +* [CSV Spec][csv] + +[config]: /getting-started/configuration/ +[csv]: https://tools.ietf.org/html/rfc4180 +[customize]: /themes/customizing/ +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[LiveReload]: /getting-started/usage/#livereload +[lookup]: /templates/lookup-order/ +[markdownify]: /functions/markdownify/ +[OAuth]: https://en.wikipedia.org/wiki/OAuth +[partials]: /templates/partials/ +[themes]: /themes/ +[toml]: https://github.com/toml-lang/toml +[variadic]: https://en.wikipedia.org/wiki/Variadic_function +[vars]: /variables/ +[yaml]: https://yaml.org/spec/ diff --git a/exampleSite/content/en/documentation/explanation/templates/files.md b/exampleSite/content/en/documentation/explanation/templates/files.md new file mode 100644 index 0000000..02d23ca --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/files.md @@ -0,0 +1,64 @@ +--- +title: Local File Templates +linktitle: Local File Templates +description: Hugo's `readDir` and `readFile` functions make it easy to traverse your project's directory structure and write file contents to your templates. +godocref: https://golang.org/pkg/os/#FileInfo +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [files,directories] + +weight: 110 +sections_weight: 110 +draft: false +aliases: [/extras/localfiles/,/templates/local-files/] +toc: true +--- + +## Traverse Local Files + +With Hugo's [`readDir`][readDir] and [`readFile`][readFile] template functions, you can traverse your website's files on your server. + +## Use `readDir` + +The [`readDir` function][readDir] returns an array of [`os.FileInfo`][osfileinfo]. It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e., as found on your server's file system). + +Whether the path is absolute or relative does not matter because---at least for `readDir`---the root of your website (typically `./public/`) in effect becomes both: + +1. The file system root +2. The current working directory + +## Use `readFile` + +The [`readfile` function][readFile] reads a file from disk and converts it into a string to be manipulated by other Hugo functions or added as-is. `readFile` takes the file, including path, as an argument passed to the function. + +To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*: + +``` +{{ readFile "/content/templates/local-file-templates" }} +``` + +### `readFile` Example: Add a Project File to Content + +As `readFile` is a function, it is only available to you in your templates and not your content. However, we can create a simple [shortcode template][sct] that calls `readFile`, passes the first argument through the function, and then allows an optional second argument to send the file through the Blackfriday markdown processor. The pattern for adding this shortcode to your content will be as follows: + +``` +{{</* readfile file="/path/to/local/file.txt" markdown="true" */>}} +``` + +{{% warning %}} +If you are going to create [custom shortcodes](/templates/shortcode-templates/) with `readFile` for a theme, note that usage of the shortcode will refer to the project root and *not* your `themes` directory. +{{% /warning %}} + + + +[called directly in the Hugo docs]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/templates/files.md +[dirindex]: https://github.com/gohugoio/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html +[osfileinfo]: https://golang.org/pkg/os/#FileInfo +[readDir]: /functions/readdir/ +[readFile]: /functions/readfile/ +[sc]: /content-management/shortcodes/ +[sct]: /templates/shortcode-templates/ +[readfilesource]: https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/readfile.html +[testfile]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/readfiles/testing.txt diff --git a/exampleSite/content/en/documentation/explanation/templates/homepage.md b/exampleSite/content/en/documentation/explanation/templates/homepage.md new file mode 100644 index 0000000..59ff22f --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/homepage.md @@ -0,0 +1,68 @@ +--- +title: Homepage Template +linktitle: Homepage Template +description: The homepage of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's homepage as a unique template. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [homepage] + +weight: 30 +sections_weight: 30 +draft: false +aliases: [/layout/homepage/,/templates/homepage-template/] +toc: true +--- + +Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use. + +{{% note "The Only Required Template" %}} +The homepage template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website. +{{% /note %}} + +{{< youtube ut1xtRZ1QOA >}} + +## Homepage Template Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +## Add Content and Front Matter to the Homepage + +The homepage, similar to other [list pages in Hugo][lists], accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` folder (i.e., `content/_index.md`). You can then add body copy and metadata to your homepage the way you would any other content file. + +See the homepage template below or [Content Organization][contentorg] for more information on the role of `_index.md` in adding content and front matter to list pages. + +## Example Homepage Template + +The following is an example of a homepage template that uses [partial][partials], [base][] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{.Content}}` [page variables][pagevars]. + +{{< code file="layouts/index.html" download="index.html" >}} +{{ define "main" }} + <main aria-role="main"> + <header class="homepage-header"> + <h1>{{.Title}}</h1> + {{ with .Params.subtitle }} + <span class="subtitle">{{.}}</span> + {{ end }} + </header> + <div class="homepage-content"> + <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md --> + {{.Content}} + </div> + <div> + {{ range first 10 .Site.RegularPages }} + {{ .Render "summary"}} + {{ end }} + </div> + </main> +{{ end }} +{{< /code >}} + +[base]: /templates/base/ +[contentorg]: /content-management/organization/ +[lists]: /templates/lists/ +[lookup]: /templates/lookup-order/ +[pagevars]: /variables/page/ +[partials]: /templates/partials/ +[sitevars]: /variables/site/ diff --git a/exampleSite/content/en/documentation/explanation/templates/internal.md b/exampleSite/content/en/documentation/explanation/templates/internal.md new file mode 100644 index 0000000..865ad6c --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/internal.md @@ -0,0 +1,209 @@ +--- +title: Internal Templates +linktitle: Internal Templates +description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites. +date: 2017-03-06 +publishdate: 2017-03-06 +lastmod: 2017-03-06 +categories: [templates] +keywords: [internal, analytics,] + +weight: 168 +sections_weight: 168 +draft: false +aliases: [] +toc: true +wip: true +--- +<!-- reference: https://discourse.gohugo.io/t/lookup-order-for-partials/5705/6 +code: https://github.com/gohugoio/hugo/blob/e445c35d6a0c7f5fc2f90f31226cd1d46e048bbc/tpl/template_embedded.go#L147 --> + +{{% warning %}} +While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order. +{{% /warning %}} + +## Google Analytics + +Hugo ships with internal templates for Google Analytics tracking, including both synchronous and asynchronous tracking codes. + +### Configure Google Analytics + +Provide your tracking id in your configuration file: + +{{< code-toggle file="config" >}} +googleAnalytics = "UA-123-45" +{{</ code-toggle >}} + +### Use the Google Analytics Template + +You can then include the Google Analytics internal template: + +``` +{{ template "_internal/google_analytics.html" . }} +``` + + +``` +{{ template "_internal/google_analytics_async.html" . }} +``` + +A `.Site.GoogleAnalytics` variable is also exposed from the config. + +## Disqus + +Hugo also ships with an internal template for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites. In order to effectively use Disqus, you will need to secure a Disqus "shortname" by [signing up for the free service][disqussignup]. + +### Configure Disqus + +To use Hugo's Disqus template, you first need to set a single value in your site's `config.toml` or `config.yml`: + +{{< code-toggle file="config" >}} +disqusShortname = "yourdiscussshortname" +{{</ code-toggle >}} + +You also have the option to set the following in the front matter for a given piece of content: + +* `disqus_identifier` +* `disqus_title` +* `disqus_url` + +### Use the Disqus Template + +To add Disqus, include the following line in templates where you want your comments to appear: + +``` +{{ template "_internal/disqus.html" . }} +``` + +A `.Site.DisqusShortname` variable is also exposed from the config. + +### Conditional Loading of Disqus Comments + +Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account. + +You can create the following `layouts/partials/disqus.html`: + +{{< code file="layouts/partials/disqus.html" download="disqus.html" >}} +<div id="disqus_thread"></div> +<script type="text/javascript"> + +(function() { + // Don't ever inject Disqus on localhost--it creates unwanted + // discussions from 'localhost:1313' on your Disqus account... + if (window.location.hostname == "localhost") + return; + + var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; + var disqus_shortname = '{{ .Site.DisqusShortname }}'; + dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js'; + (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); +})(); +</script> +<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript> +<a href="https://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a> +{{< /code >}} + +The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`. + +You can then render your custom Disqus partial template as follows: + +``` +{{ partial "disqus.html" . }} +``` + +## Open Graph +An internal template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph. +This format is used for Facebook and some other sites. + +### Configure Open Graph + +Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. + +{{< code-toggle file="config" >}} +[params] + title = "My cool site" + images = ["site-feature-image.jpg"] + description = "Text about my cool site" +[taxonomies] + series = "series" +{{</ code-toggle >}} + +{{< code-toggle file="content/blog/my-post" >}} +title = "Post title" +description = "Text about this post" +date = "2006-01-02" +images = ["post-cover.png"] +audio = [] +videos = [] +series = [] +tags = [] +{{</ code-toggle >}} + +Hugo uses the page title and description for the title and description metadata. +The first 6 URLs from the `images` array are used for image metadata. + +Various optional metadata can also be set: + +- Date, published date, and last modified data are used to set the published time metadata if specified. +- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively. +- The first 6 `tags` on the page are used for the tags metadata. +- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series. + +If using YouTube this will produce a og:video tag like `<meta property="og:video" content="url">`. Use the `https://youtu.be/<id>` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`). + +### Use the Open Graph Template + +To add Open Graph metadata, include the following line between the `<head>` tags in your templates: + +``` +{{ template "_internal/opengraph.html" . }} +``` + +## Twitter Cards + +An internal template for [Twitter Cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards), +metadata used to attach rich media to Tweets linking to your site. + +### Configure Twitter Cards + +Hugo's Twitter Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. + +{{< code-toggle file="config" >}} +[params] + images = ["site-feature-image.jpg"] + description = "Text about my cool site" +{{</ code-toggle >}} + +{{< code-toggle file="content/blog/my-post" >}} +title = "Post title" +description = "Text about this post" +images = ["post-cover.png"] +{{</ code-toggle >}} + +If `images` aren't specified in the page front-matter, then hugo searches for [image page resources](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name. +If no image resources with those names are found, the images defined in the [site config](/getting-started/configuration/) are used instead. +If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`. + +Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given. + +### Use the Twitter Cards Template + +To add Twitter card metadata, include the following line between the `<head>` tags in your templates: + +``` +{{ template "_internal/twitter_cards.html" . }} +``` + +## The Internal Templates + +* `_internal/disqus.html` +* `_internal/google_news.html` +* `_internal/google_analytics.html` +* `_internal/google_analytics_async.html` +* `_internal/opengraph.html` +* `_internal/pagination.html` +* `_internal/schema.html` +* `_internal/twitter_cards.html` + +[disqus]: https://disqus.com +[disqussignup]: https://disqus.com/profile/signup/ diff --git a/exampleSite/content/en/documentation/explanation/templates/introduction.md b/exampleSite/content/en/documentation/explanation/templates/introduction.md new file mode 100644 index 0000000..bc7a404 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/introduction.md @@ -0,0 +1,659 @@ +--- +title: Introduction to Hugo Templating +linktitle: Introduction +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. +godocref: https://golang.org/pkg/html/template/ +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-25 +categories: [templates,fundamentals] +keywords: [go] + +weight: 10 +sections_weight: 10 +draft: false +aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/] +toc: true +--- + +{{% note %}} +The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](https://golang.org/pkg/text/template/). +{{% /note %}} + +Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. + +## Basic Syntax + +Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`. + +### Access a Predefined Variable + +A _predefined variable_ could be a variable already existing in the +current scope (like the `.Title` example in the [Variables]({{< relref +"#variables" >}}) section below) or a custom variable (like the +`$address` example in that same section). + + +```go-html-template +{{ .Title }} +{{ $address }} +``` + +Parameters for functions are separated using spaces. The general syntax is: + +``` +{{ FUNCTION ARG1 ARG2 .. }} +``` + +The following example calls the `add` function with inputs of `1` and `2`: + +```go-html-template +{{ add 1 2 }} +``` + +#### Methods and Fields are Accessed via dot Notation + +Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. + +```go-html-template +{{ .Params.bar }} +``` + +#### Parentheses Can be Used to Group Items Together + +```go-html-template +{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +``` + +## Variables {#variables} + +Each Go Template gets a data object. In Hugo, each template is passed +a `Page`. In the below example, `.Title` is one of the elements +accessible in that [`Page` variable][pagevars]. + +With the `Page` being the default scope of a template, the `Title` +element in current scope (`.` -- "the **dot**") is accessible simply +by the dot-prefix (`.Title`): + +```go-html-template +<title>{{ .Title }}</title> +``` + +Values can also be stored in custom variables and referenced later: + +{{% note %}} +The custom variables need to be prefixed with `$`. +{{% /note %}} + +```go-html-template +{{ $address := "123 Main St." }} +{{ $address }} +``` + +{{% warning %}} +For Hugo v0.47 and older versions, variables defined inside `if` +conditionals and similar are not visible on the outside. +See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). + +Hugo has created a workaround for this issue in [Scratch](/functions/scratch). +{{% /warning %}} + +For **Hugo v0.48** and newer, variables can be re-defined using the +new `=` operator (new in Go 1.11). + +Below example will work only in these newer Hugo versions. The example +prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on +all other pages: + +```go-html-template +{{ $var := "Hugo Page" }} +{{ if .IsHome }} + {{ $var = "Hugo Home" }} +{{ end }} +Var is {{ $var }} +``` + +## Functions + +Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. + +[Hugo template functions][functions] provide additional functionality specific to 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 1: Adding Numbers + +```go-html-template +{{ add 1 2 }} +<!-- prints 3 --> +``` + +### Example 2: Comparing Numbers + +```go-html-template +{{ lt 1 2 }} +<!-- prints true (i.e., since 1 is less than 2) --> +``` + +Note that both examples make use of Go Template's [math functions][]. + +{{% note "Additional Boolean Operators" %}} +There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions). +{{% /note %}} + +## Includes + +When including another template, you will need to pass it the data that it would +need to access. + +{{% note %}} +To pass along the current context, please remember to include a trailing **dot**. +{{% /note %}} + +The templates location will always be starting at the `layouts/` directory +within Hugo. + +### Partial + +The [`partial`][partials] function is used to include *partial* templates using +the syntax `{{ partial "<PATH>/<PARTIAL>.<EXTENSION>" . }}`. + +Example of including a `layouts/partials/header.html` partial: + +```go-html-template +{{ partial "header.html" . }} +``` + +### Template + +The `template` function was used to include *partial* templates +in much older Hugo versions. Now it's useful only for calling +[*internal* templates][internal_templates]. The syntax is `{{ template +"_internal/<TEMPLATE>.<EXTENSION>" . }}`. + +{{% note %}} +The available **internal** templates can be found +[here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates). +{{% /note %}} + +Example of including the internal `opengraph.html` template: + +```go-html-template +{{ template "_internal/opengraph.html" . }} +``` + +## Logic + +Go Templates provide the most basic iteration and conditional logic. + +### Iteration + +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 (`.`) + +```go-html-template +{{ range $array }} + {{ . }} <!-- The . represents an element in $array --> +{{ end }} +``` + +#### Example 2: Declaring a variable name for an array element's value + +```go-html-template +{{ range $elem_val := $array }} + {{ $elem_val }} +{{ end }} +``` + +#### Example 3: Declaring variable names for an array element's index _and_ value + +For an array or slice, the first declared variable will map to each +element's index. + +```go-html-template +{{ range $elem_index, $elem_val := $array }} + {{ $elem_index }} -- {{ $elem_val }} +{{ end }} +``` + +#### Example 4: Declaring variable names for a map element's key _and_ value + +For a map, the first declared variable will map to each map element's +key. + +```go-html-template +{{ range $elem_key, $elem_val := $map }} + {{ $elem_key }} -- {{ $elem_val }} +{{ end }} +``` + +#### Example 5: Conditional on empty _map_, _array_, or _slice_. + +If the _map_, _array_, or _slice_ passed into the range is zero-length then the else statement is evaluated. + +```go-html-template +{{ range $array }} + {{ . }} +{{else}} + <!-- This is only evaluated if $array is empty --> +{{ end }} +``` + +### Conditionals + +`if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{ end }}`. + +Go Templates treat the following values as **false**: + +- `false` (boolean) +- 0 (integer) +- any zero-length array, slice, map, or string + +#### Example 1: `with` + +It is common to write "if something exists, do this" kind of +statements using `with`. + +{{% note %}} +`with` rebinds the context `.` within its scope (just like in `range`). +{{% /note %}} + +It skips the block if the variable is absent, or if it evaluates to +"false" as explained above. + +```go-html-template +{{ with .Params.title }} + <h4>{{ . }}</h4> +{{ end }} +``` + +#### Example 2: `with` .. `else` + +Below snippet uses the "description" front-matter parameter's value if +set, else uses the default `.Summary` [Page variable][pagevars]: + + +```go-html-template +{{ with .Param "description" }} + {{ . }} +{{ else }} + {{ .Summary }} +{{ end }} +``` + +See the [`.Param` function][param]. + +#### Example 3: `if` + +An alternative (and a more verbose) way of writing `with` is using +`if`. Here, the `.` does not get rebinded. + +Below example is "Example 1" rewritten using `if`: + +```go-html-template +{{ if isset .Params "title" }} + <h4>{{ index .Params "title" }}</h4> +{{ end }} +``` + +#### Example 4: `if` .. `else` + +Below example is "Example 2" rewritten using `if` .. `else`, and using +[`isset` function][isset] + `.Params` variable (different from the +[`.Param` **function**][param]) instead: + +```go-html-template +{{ if (isset .Params "description") }} + {{ index .Params "description" }} +{{ else }} + {{ .Summary }} +{{ end }} +``` + +#### Example 5: `if` .. `else if` .. `else` + +Unlike `with`, `if` can contain `else if` clauses too. + +```go-html-template +{{ if (isset .Params "description") }} + {{ index .Params "description" }} +{{ else if (isset .Params "summary") }} + {{ index .Params "summary" }} +{{ else }} + {{ .Summary }} +{{ end }} +``` + +#### Example 6: `and` & `or` + +```go-html-template +{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }} +``` + +## 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 can only 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: `shuffle` + +The following two examples are functionally the same: + +```go-html-template +{{ shuffle (seq 1 5) }} +``` + + +```go-html-template +{{ (seq 1 5) | shuffle }} +``` + +### Example 2: `index` + +The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function](/functions/index-function/), which is built into Go Templates: + +```go-html-template +{{ index .Params "disqus_url" | html }} +``` + +### Example 3: `or` with `isset` + +```go-html-template +{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }} +Stuff Here +{{ end }} +``` + +Could be rewritten as + +```go-html-template +{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }} +Stuff Here +{{ end }} +``` + +### Example 4: Internet Explorer Conditional Comments {#ie-conditional-comments} + +By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this: + +```go-html-template +{{ "<!--[if lt IE 9]>" | safeHTML }} + <script src="html5shiv.js"></script> +{{ "<![endif]-->" | safeHTML }} +``` + +Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional comments, avoiding the tedious task of escaping every double quotes (`"`) inside, as demonstrated in the [examples](https://golang.org/pkg/text/template/#hdr-Examples) in the Go text/template documentation: + +```go-html-template +{{ `<!--[if lt IE 7]><html class="no-js lt-ie9 lt-ie8 lt-ie7"><![endif]-->` | safeHTML }} +``` + +## Context (aka "the dot") {#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 an iteration, however, it will have the value of the + current item in the loop; i.e., `{{ . }}` will no longer refer to + the data available to the entire page. + +If you need to access page-level data (e.g., page params set in front +matter) from within the loop, you will likely want to do one of the +following: + +### 1. Define a Variable Independent of Context + +The following shows how to define a variable independent of the context. + +{{< code file="tags-range-with-page-variable.html" >}} +{{ $title := .Site.Title }} +<ul> +{{ range .Params.tags }} + <li> + <a href="/tags/{{ . | urlize }}">{{ . }}</a> + - {{ $title }} + </li> +{{ end }} +</ul> +{{< /code >}} + +{{% note %}} +Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well. +{{% /note %}} + +### 2. Use `$.` to Access the Global Context + +`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context: + +{{< code file="range-through-tags-w-global.html" >}} +<ul> +{{ range .Params.tags }} + <li> + <a href="/tags/{{ . | urlize }}">{{ . }}</a> + - {{ $.Site.Title }} + </li> +{{ end }} +</ul> +{{< /code >}} + +{{% warning "Don't Redefine the Dot" %}} +The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value. +{{% /warning %}} + +## Whitespace + +Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter. + +For instance, the following Go Template will include the newlines and horizontal tab in its HTML output: + +```go-html-template +<div> + {{ .Title }} +</div> +``` + +Which will output: + +```html +<div> + Hello, World! +</div> +``` + +Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline: + +```go-html-template +<div> + {{- .Title -}} +</div> +``` + +Which then outputs: + +```html +<div>Hello, World!</div> +``` + +Go considers the following characters _whitespace_: + +* <kbd>space</kbd> +* horizontal <kbd>tab</kbd> +* carriage <kbd>return</kbd> +* newline + +## Comments + +In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo. + +### Go Templates comments + +Go Templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered. + +For example: + +```go-html-template +Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott. +``` + +Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block. + +### HTML comments + +If you need to produce HTML comments from your templates, take a look at the [Internet Explorer conditional comments](#ie-conditional-comments) example. If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`. For example: + +```go-html-template +{{ printf "<!-- Our website is named: %s -->" .Site.Title | safeHTML }} +``` + +#### HTML comments containing Go Templates + +HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process. + +{{% note %}} +Do **not** try to comment out Go Template code using HTML comments. +{{% /note %}} + +```go-html-template +<!-- {{ $author := "Emma Goldman" }} was a great woman. --> +{{ $author }} +``` + +The templating engine will strip the content within the HTML comment, but will first evaluate any Go Template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error. + +## Hugo Parameters + +Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format]({{< ref "front-matter.md#front-matter-formats" >}}). + +## Use Content (`Page`) Parameters + +You can provide variables to be used by templates in individual content's [front matter][]. + +An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`. + +Here is the example front matter (YAML): + +``` +--- +title: Roadmap +lastmod: 2017-03-05 +date: 2013-11-18 +notoc: true +--- +``` + +Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]: + +{{< code file="layouts/partials/toc.html" download="toc.html" >}} +{{ if not .Params.notoc }} +<aside> + <header> + <a href="#{{.Title | urlize}}"> + <h3>{{.Title}}</h3> + </a> + </header> + {{.TableOfContents}} +</aside> +<a href="#" id="toc-toggle"></a> +{{ end }} +{{< /code >}} + +We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`. + +## Use Site Configuration Parameters + +You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates. + +For instance, you might declare the following: + +{{< code-toggle file="config" >}} +params: + copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved." + twitteruser: "spf13" + sidebarrecentlimit: 5 +{{< /code >}} + +Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates. + +```go-html-template +{{ if .Site.Params.copyrighthtml }} + <footer> + <div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div> + </footer> +{{ end }} +``` + +An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent: + +{{< code file="layouts/partials/twitter.html" >}} +{{ with .Site.Params.twitteruser }} + <div> + <a href="https://twitter.com/{{.}}" rel="author"> + <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a> + </div> +{{ end }} +{{< /code >}} + +Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable. + +```go-html-template +<nav> + <h1>Recent Posts</h1> + <ul> + {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}} + <li><a href="{{.RelPermalink}}">{{.Title}}</a></li> + {{- end -}} + </ul> +</nav> +``` + +## Example: Show Only Upcoming Events + +Go allows you to do more than what's shown here. Using Hugo's [`where` function][where] and Go built-ins, we can list only the items from `content/events/` whose date (set in a content file's [front matter][]) is in the future. The following is an example [partial template][partials]: + +{{< code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" >}} +<h4>Upcoming Events</h4> +<ul class="upcoming-events"> +{{ range where .Pages.ByDate "Section" "events" }} + {{ if ge .Date.Unix now.Unix }} + <li> + <!-- add span for event type --> + <span>{{ .Type | title }} —</span> + {{ .Title }} on + <!-- add span for event date --> + <span>{{ .Date.Format "2 January at 3:04pm" }}</span> + at {{ .Params.place }} + </li> + {{ end }} +{{ end }} +</ul> +{{< /code >}} + + +[`where` function]: /functions/where/ +[config]: /getting-started/configuration/ +[dotdoc]: https://golang.org/pkg/text/template/#hdr-Variables +[first]: /functions/first/ +[front matter]: /content-management/front-matter/ +[functions]: /functions/ "See the full list of Hugo's templating functions with a quick start reference guide and basic and advanced examples." +[Go html/template]: https://golang.org/pkg/html/template/ "Godocs references for Go's html templating" +[gohtmltemplate]: https://golang.org/pkg/html/template/ "Godocs references for Go's html templating" +[index]: /functions/index-function/ +[math functions]: /functions/math/ +[partials]: /templates/partials/ "Link to the partial templates page inside of the templating section of the Hugo docs" +[internal_templates]: /templates/internal/ +[relpermalink]: /variables/page/ +[safehtml]: /functions/safehtml/ +[sitevars]: /variables/site/ +[pagevars]: /variables/page/ +[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates." +[where]: /functions/where/ +[with]: /functions/with/ +[godocsindex]: https://golang.org/pkg/text/template/ "Godocs page for index function" +[param]: /functions/param/ +[isset]: /functions/isset/ diff --git a/exampleSite/content/en/documentation/explanation/templates/lists.md b/exampleSite/content/en/documentation/explanation/templates/lists.md new file mode 100644 index 0000000..1f46cff --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/lists.md @@ -0,0 +1,590 @@ +--- +title: Lists of Content in Hugo +linktitle: List Page Templates +description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [lists,sections,rss,taxonomies,terms] + +weight: 22 +sections_weight: 22 +draft: false +aliases: [/templates/list/,/layout/indexes/] +toc: true +--- + +## What is a List Page Template? + +{{< youtube 8b2YTSMdMps >}} + +A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage]. + +Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed: + +* [Taxonomy terms pages][taxterms] +* [Taxonomy list pages][taxlists] +* [Section list pages][sectiontemps] +* [RSS][rss] + +For template lookup order, see [Template Lookup](/templates/lookup-order/). + +The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually: + +[](/images/site-hierarchy.svg) + +## List Defaults + +### Default Templates + +Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html` or `themes/<THEME>/layouts/_default/list.html` in their lookup order. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`. + +See [Template Lookup Order](/templates/lookup-order/) for the complete reference. + +## Add Content and Front Matter to List Pages + +Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files (i.e. `_index.md`) that contain page metadata (i.e., front matter) and content. + +This new model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) have access to all [page variables][pagevars]. + +{{% note %}} +It is important to note that all `_index.md` content files will render according to a *list* template and not according to a [single page template](/templates/single-page-templates/). +{{% /note %}} + +### Example Project Directory + +The following is an example of a typical Hugo project directory's content: + +``` +. +... +├── content +| ├── posts +| | ├── _index.md +| | ├── post-01.md +| | └── post-02.md +| └── quote +| | ├── quote-01.md +| | └── quote-02.md +... +``` + +Using the above example, let's assume you have the following in `content/posts/_index.md`: + +{{< code file="content/posts/_index.md" >}} +--- +title: My Go Journey +date: 2017-03-23 +publishdate: 2017-03-24 +--- + +I decided to start learning Go in March 2017. + +Follow my journey through this new blog. +{{< /code >}} + +You can now access this `_index.md`'s' content in your list template: + +{{< code file="layouts/_default/list.html" download="list.html" >}} +{{ define "main" }} +<main> + <article> + <header> + <h1>{{.Title}}</h1> + </header> + <!-- "{{.Content}}" pulls from the markdown content of the corresponding _index.md --> + {{.Content}} + </article> + <ul> + <!-- Ranges through content/posts/*.md --> + {{ range .Pages }} + <li> + <a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a> + </li> + {{ end }} + </ul> +</main> +{{ end }} +{{< /code >}} + +This above will output the following HTML: + +{{< code file="example.com/posts/index.html" copy="false" >}} +<!--top of your baseof code--> +<main> + <article> + <header> + <h1>My Go Journey</h1> + </header> + <p>I decided to start learning Go in March 2017.</p> + <p>Follow my journey through this new blog.</p> + </article> + <ul> + <li><a href="/posts/post-01/">Post 1</a></li> + <li><a href="/posts/post-02/">Post 2</a></li> + </ul> +</main> +<!--bottom of your baseof--> +{{< /code >}} + +### List Pages Without `_index.md` + +You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a list template, the page will be created but with no `{{.Content}}` and only the default values for `.Title` etc. + +Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from: + +{{< code file="example.com/quote/index.html" copy="false" >}} +<!--baseof--> +<main> + <article> + <header> + <!-- Hugo assumes that .Title is the name of the section since there is no _index.md content file from which to pull a "title:" field --> + <h1>Quotes</h1> + </header> + </article> + <ul> + <li><a href="https://example.com/quote/quotes-01/">Quote 1</a></li> + <li><a href="https://example.com/quote/quotes-02/">Quote 2</a></li> + </ul> +</main> +<!--baseof--> +{{< /code >}} + +{{% note %}} +The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/). +{{% /note %}} + +## Example List Templates + +### Section Template + +This list template has been modified slightly from a template originally used in [spf13.com](http://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base]. The examples that follow also use the [content view templates][views] `li.html` or `summary.html`. + +{{< code file="layouts/section/posts.html" >}} +{{ partial "header.html" . }} +{{ partial "subheader.html" . }} +<main> + <div> + <h1>{{ .Title }}</h1> + <ul> + <!-- Renders the li.html content view for each content/posts/*.md --> + {{ range .Pages }} + {{ .Render "li"}} + {{ end }} + </ul> + </div> +</main> +{{ partial "footer.html" . }} +{{< /code >}} + +### Taxonomy Template + +{{< code file="layouts/_default/taxonomy.html" download="taxonomy.html" >}} +{{ define "main" }} +<main> + <div> + <h1>{{ .Title }}</h1> + <!-- ranges through each of the content files associated with a particular taxonomy term and renders the summary.html content view --> + {{ range .Pages }} + {{ .Render "summary"}} + {{ end }} + </div> +</main> +{{ end }} +{{< /code >}} + +## Order Content + +Hugo lists render the content based on metadata you provide in [front matter][]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates: + +### Default: Weight > Date > LinkTitle > FilePath + +{{< code file="layouts/partials/default-order.html" >}} +<ul> + {{ range .Pages }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Weight + +Lower weight gets higher precedence. So content with lower weight will come first. + +{{< code file="layouts/partials/by-weight.html" >}} +<ul> + {{ range .Pages.ByWeight }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Date + +{{< code file="layouts/partials/by-date.html" >}} +<ul> + <!-- orders content according to the "date" field in front matter --> + {{ range .Pages.ByDate }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Publish Date + +{{< code file="layouts/partials/by-publish-date.html" >}} +<ul> + <!-- orders content according to the "publishdate" field in front matter --> + {{ range .Pages.ByPublishDate }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Expiration Date + +{{< code file="layouts/partials/by-expiry-date.html" >}} +<ul> + {{ range .Pages.ByExpiryDate }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Last Modified Date + +{{< code file="layouts/partials/by-last-mod.html" >}} +<ul> + <!-- orders content according to the "lastmod" field in front matter --> + {{ range .Pages.ByLastmod }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Length + +{{< code file="layouts/partials/by-length.html" >}} +<ul> + <!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) --> + {{ range .Pages.ByLength }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Title + +{{< code file="layouts/partials/by-title.html" >}} +<ul> + <!-- ranges through content in ascending order according to the "title" field set in front matter --> + {{ range .Pages.ByTitle }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Link Title + +{{< code file="layouts/partials/by-link-title.html" >}} +<ul> + <!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle --> + {{ range .Pages.ByLinkTitle }} + <li> + <h1><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Parameter + +Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering. + +{{< code file="layouts/partials/by-rating.html" >}} +<!-- Ranges through content according to the "rating" field set in front matter --> +{{ range (.Pages.ByParam "rating") }} + <!-- ... --> +{{ end }} +{{< /code >}} + +If the targeted front matter field is nested beneath another field, you can access the field using dot notation. + +{{< code file="layouts/partials/by-nested-param.html" >}} +{{ range (.Pages.ByParam "author.last_name") }} + <!-- ... --> +{{ end }} +{{< /code >}} + +### Reverse Order + +Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example: + +{{< code file="layouts/partials/by-date-reverse.html" >}} +<ul> + {{ range .Pages.ByDate.Reverse }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +## Group Content + +Hugo provides some functions for grouping pages by Section, Type, Date, etc. + +### By Page Field + +{{< code file="layouts/partials/by-page-field.html" >}} +<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. --> +{{ range .Pages.GroupBy "Section" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +In the above example, you may want `{{.Title}}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]: + +{{< code file="layouts/partials/by-page-field.html" >}} +<!-- Groups content according to content section.--> +{{ range .Pages.GroupBy "Section" }} +<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter --> +{{ with $.Site.GetPage "section" .Key }} +<h3>{{.Title}}</h3> +{{ else }} +<!-- If no _index.md is available, ".Key" defaults to the section title and filters to title casing --> +<h3>{{ .Key | title }}</h3> +{{ end }} +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### By Date + +{{< code file="layouts/partials/by-page-date.html" >}} +<!-- Groups content by month according to the "date" field in front matter --> +{{ range .Pages.GroupByDate "2006-01" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### By Publish Date + +{{< code file="layouts/partials/by-page-publish-date.html" >}} +<!-- Groups content by month according to the "publishDate" field in front matter --> +{{ range .Pages.GroupByPublishDate "2006-01" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + + +### By Lastmod + +{{< code file="layouts/partials/by-page-lastmod.html" >}} +<!-- Groups content by month according to the "lastMod" field in front matter --> +{{ range .Pages.GroupByLastmod "2006-01" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Lastmod.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### By Expiry Date + +{{< code file="layouts/partials/by-page-expiry-date.html" >}} +<!-- Groups content by month according to the "expiryDate" field in front matter --> +{{ range .Pages.GroupByExpiryDate "2006-01" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### By Page Parameter + +{{< code file="layouts/partials/by-page-param.html" >}} +<!-- Groups content according to the "param_key" field in front matter --> +{{ range .Pages.GroupByParam "param_key" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### By Page Parameter in Date Format + +The following template takes grouping by `date` a step further and uses Go's layout string. See the [`Format` function][] for more examples of how to use Go's layout string to format dates in Hugo. + +{{< code file="layouts/partials/by-page-param-as-date.html" >}} +<!-- Groups content by month according to the "param_key" field in front matter --> +{{ range .Pages.GroupByParamDate "param_key" "2006-01" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### Reverse Key Order + +Ordering of groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (i.e., with the newest first) for dates. + +While these are logical defaults, they are not always the desired order. There are two different syntaxes to change Hugo's default ordering for groups, both of which work the same way. + +#### 1. Adding the Reverse Method + +``` +{{ range (.Pages.GroupBy "Section").Reverse }} +``` + +``` +{{ range (.Pages.GroupByDate "2006-01").Reverse }} +``` + +#### 2. Providing the Alternate Direction + +``` +{{ range .Pages.GroupByDate "2006-01" "asc" }} +``` + +``` +{{ range .Pages.GroupBy "Section" "desc" }} +``` + +### Order Within Groups + +Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available. + +Here is the ordering for the example that follows: + +1. Content is grouped by month according to the `date` field in front matter. +2. Groups are listed in ascending order (i.e., the oldest groups first) +3. Pages within each respective group are ordered alphabetically according to the `title`. + +{{< code file="layouts/partials/by-group-by-page.html" >}} +{{ range .Pages.GroupByDate "2006-01" "asc" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages.ByTitle }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +## Filtering and Limiting Lists {#filtering-and-limiting-lists} + +Sometimes you only want to list a subset of the available content. A +common is to only display posts from [**main sections**][mainsections] +on the blog's homepage. + +See the documentation on [`where` function][wherefunction] and +[`first` function][firstfunction] for further details. + +[base]: /templates/base/ +[bepsays]: https://bepsays.com/en/2016/12/19/hugo-018/ +[directorystructure]: /getting-started/directory-structure/ +[`Format` function]: /functions/format/ +[front matter]: /content-management/front-matter/ +[getpage]: /functions/getpage/ +[homepage]: /templates/homepage/ +[homepage]: /templates/homepage/ +[mentalmodel]: https://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html +[pagevars]: /variables/page/ +[partials]: /templates/partials/ +[RSS 2.0]: https://cyber.harvard.edu/rss/rss.html "RSS 2.0 Specification" +[rss]: /templates/rss/ +[sections]: /content-management/sections/ +[sectiontemps]: /templates/section-templates/ +[sitevars]: /variables/site/ +[taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates +[taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates +[taxvars]: /variables/taxonomy/ +[views]: /templates/views/ +[wherefunction]: /functions/where/ +[firstfunction]: /functions/first/ +[mainsections]: /functions/where/#mainsections diff --git a/exampleSite/content/en/documentation/explanation/templates/lookup-order.md b/exampleSite/content/en/documentation/explanation/templates/lookup-order.md new file mode 100644 index 0000000..f823d58 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/lookup-order.md @@ -0,0 +1,81 @@ +--- +title: Hugo's Lookup Order +linktitle: Template Lookup Order +description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-07-05 +categories: [templates,fundamentals] +keywords: [templates] + +weight: 15 +sections_weight: 15 +draft: false +aliases: [/templates/lookup/] +toc: true +--- + +## Hugo Layouts Lookup Rules + +Hugo takes the parameters listed below into consideration when choosing a layout for a given page. They are listed in a priority order. This should feel natural, but look at the table below for concrete examples of the different parameter variations. + + +Kind +: The page `Kind` (the home page is one). See the example tables below per kind. This also determines if it is a **single page** (i.e. a regular content page. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML). + +Layout +: Can be set in page front matter. + +Output Format +: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`, but look for less specific templates. + +Language +: We will consider a language code in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but `index.amp.html` will be chosen before `index.fr.html`. + +Type +: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). It will always have a value, so if not set, the value is "page". + +Section +: Is relevant for `section`, `taxonomy` and `term` types. + +{{% note %}} +**Tip:** The examples below looks long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates: + +```bash +├── _default +│ ├── baseof.html +│ ├── list.html +│ └── single.html +└── index.html +``` +{{% /note %}} + + +## Hugo Layouts Lookup Rules With Theme + +In Hugo, layouts can live in either the project's or the themes' layout folders, and the most specific layout will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes. + +## Examples: Layout Lookup for Regular Pages + +{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Home Page + +{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Section Pages + +{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Taxonomy Pages + +{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Term Pages + +{{< datatable-filtered "output" "layouts" "Kind == term" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + + + + diff --git a/exampleSite/content/en/documentation/explanation/templates/menu-templates.md b/exampleSite/content/en/documentation/explanation/templates/menu-templates.md new file mode 100644 index 0000000..278f74a --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/menu-templates.md @@ -0,0 +1,170 @@ +--- +title: +weight: 130 +sections_weight: 130 +draft: false +aliases: [/templates/menus/] +toc: false +--- + +Hugo makes no assumptions about how your rendered HTML will be +structured. Instead, it provides all of the functions you will need to be +able to build your menu however you want. + +The following is an example: + +{{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}} +<!-- sidebar start --> +<aside> + <ul> + {{ $currentPage := . }} + {{ range .Site.Menus.main }} + {{ if .HasChildren }} + <li class="{{ if $currentPage.HasMenuCurrent "main" . }}active{{ end }}"> + <a href="#"> + {{ .Pre }} + <span>{{ .Name }}</span> + </a> + </li> + <ul class="sub-menu"> + {{ range .Children }} + <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}"> + <a href="{{ .URL }}">{{ .Name }}</a> + </li> + {{ end }} + </ul> + {{ else }} + <li> + <a href="{{ .URL }}"> + {{ .Pre }} + <span>{{ .Name }}</span> + </a> + </li> + {{ end }} + {{ end }} + <li> + <a href="#" target="_blank">Hardcoded Link 1</a> + </li> + <li> + <a href="#" target="_blank">Hardcoded Link 2</a> + </li> + </ul> +</aside> +{{< /code >}} + +{{% note "`absLangURL` and `relLangURL`" %}} +Use the [`absLangURL`](/functions/abslangurl) or [`relLangURL`](/functions/rellangurl) functions if your theme makes use of the [multilingual feature](/content-management/multilingual/). In contrast to `absURL` and `relURL`, these two functions add the correct language prefix to the url. +{{% /note %}} + +## Section Menu for Lazy Bloggers + +To enable this menu, configure `sectionPagesMenu` in your site `config`: + +``` +sectionPagesMenu = "main" +``` + +The menu name can be anything, but take a note of what it is. + +This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this: + +``` +<nav class="sidebar-nav"> + {{ $currentPage := . }} + {{ range .Site.Menus.main }} + <a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{ .URL }}" title="{{ .Title }}">{{ .Name }}</a> + {{ end }} +</nav> +``` + +In the above, the menu item is marked as active if on the current section's list page or on a page in that section. + + +## Site Config menus + +The above is all that's needed. But if you want custom menu items, e.g. changing weight, name, or link title attribute, you can define them manually in the site config file: + +{{< code-toggle file="config" >}} +[[menu.main]] + name = "This is the blog section" + title = "blog section" + weight = -110 + identifier = "blog" + url = "/blog/" +{{</ code-toggle >}} + +{{% note %}} +The `identifier` *must* match the section name. +{{% /note %}} + +## Menu Entries from the Page's front matter + +It's also possible to create menu entries from the page (i.e. the `.md`-file). + +Here is a `yaml` example: + +``` +--- +title: Menu Templates +linktitle: Menu Templates +menu: + docs: + title: "how to use menus in templates" + parent: "templates" + weight: 130 +--- +... +``` + +{{% note %}} +You can define more than one menu. It also doesn't have to be a complex value, +`menu` can also be a string, an array of strings, or an array of complex values +like in the example above. +{{% /note %}} + +### Using .Page in Menus + +If you use the front matter method of defining menu entries, you'll get access to the `.Page` variable. +This allows to use every variable that's reachable from the [page variable](/variables/page/). + +This variable is only set when the menu entry is defined in the page's front matter. +Menu entries from the site config don't know anything about `.Page`. + +That's why you have to use the go template's `with` keyword or something similar in your templating language. + +Here's an example: + +``` +<nav class="sidebar-nav"> + {{ range .Site.Menus.main }} + <a href="{{ .URL }}" title="{{ .Title }}"> + {{- .Name -}} + {{- with .Page -}} + <span class="date"> + {{- dateFormat " (2006-01-02)" .Date -}} + </span> + {{- end -}} + </a> + {{ end }} +</nav> +``` + +## Using .Params in Menus + +User-defined content on menu items are accessible via `.Params`. + +Here's an example: + +``` +<nav class="sidebar-nav"> + {{ range .Site.Menus.main }} + <a href="{{ .URL }}" title="{{ .Title }}" class="{{ with .Params.class }}{{ . }}{{ end }}"> + {{- .Name -}} + </a> + {{ end }} +</nav> +``` + +{{% note %}} +With Menu-level .Params they can easily exist on one menu item but not another. It's recommended to access them gracefully using the [with function](/functions/with). +{{% /note %}}
\ No newline at end of file diff --git a/exampleSite/content/en/documentation/explanation/templates/ordering-and-grouping.md b/exampleSite/content/en/documentation/explanation/templates/ordering-and-grouping.md new file mode 100644 index 0000000..ec6bb75 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/ordering-and-grouping.md @@ -0,0 +1,341 @@ +--- +title: Ordere and Grouping Hugo Lists +linktitle: List Ordering and Grouping +description: You can group or order your content in both your templating and content front matter. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [] + +weight: 27 +sections_weight: 27 +draft: true +aliases: [/templates/ordering/,/templates/grouping/] +toc: true +notes: This was originally going to be a separate page on the new docs site but it now makes more sense to keep everything within the templates/lists page. - rdwatters, 2017-03-12. +--- + +In Hugo, A list template is any template that will be used to render multiple pieces of content in a single HTML page. + +## Example List Templates + +### Section Template + +This list template is used for [spf13.com](https://spf13.com/). It makes use of [partial templates][partials]. All examples use a [view](/templates/views/) called either "li" or "summary." + +{{< code file="layouts/section/post.html" >}} +{{ partial "header.html" . }} +{{ partial "subheader.html" . }} + +<section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + <ul id="list"> + {{ range .Pages }} + {{ .Render "li"}} + {{ end }} + </ul> + </div> +</section> +{{ partial "footer.html" . }} +{{< /code >}} + +### Taxonomy Template + +{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}} +{{ define "main" }} +<section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Pages }} + {{ .Render "summary"}} + {{ end }} + </div> +</section> +{{ end }} +{{< /code >}} + +## Order Content + +Hugo lists render the content based on metadata provided in the [front matter](/content-management/front-matter/).. + +Here are a variety of different ways you can order the content items in +your list templates: + +### Default: Weight > Date + +{{< code file="layouts/partials/order-default.html" >}} +<ul class="pages"> + {{ range .Pages }} + <li> + <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1> + <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time> + </li> + {{ end }} +</ul> +{{< /code >}} + +### By Weight + +{{< code file="layouts/partials/by-weight.html" >}} +{{ range .Pages.ByWeight }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> +{{ end }} +{{< /code >}} + +### By Date + +{{< code file="layouts/partials/by-date.html" >}} +{{ range .Pages.ByDate }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> +{{ end }} +{{< /code >}} + +### By Publish Date + +{{< code file="layouts/partials/by-publish-date.html" >}} +{{ range .Pages.ByPublishDate }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div> + </li> +{{ end }} +{{< /code >}} + +### By Expiration Date + +{{< code file="layouts/partials/by-expiry-date.html" >}} +{{ range .Pages.ByExpiryDate }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div> + </li> +{{ end }} +{{< /code >}} + +### By Last Modified Date + +{{< code file="layouts/partials/by-last-mod.html" >}} +{{ range .Pages.ByLastmod }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> +{{ end }} +{{< /code >}} + +### By Length + +{{< code file="layouts/partials/by-length.html" >}} +{{ range .Pages.ByLength }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> +{{ end }} +{{< /code >}} + + +### By Title + +{{< code file="layouts/partials/by-title.html" >}} +{{ range .Pages.ByTitle }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> +{{ end }} +{{< /code >}} + +### By Link Title + +{{< code file="layouts/partials/by-link-title.html" >}} +{{ range .Pages.ByLinkTitle }} + <li> + <a href="{{ .Permalink }}">{{ .LinkTitle }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> +{{ end }} +{{< /code >}} + +### By Parameter + +Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering. + +The below example sorts a list of posts by their rating. + +{{< code file="layouts/partials/by-rating.html" >}} +{{ range (.Pages.ByParam "rating") }} + <!-- ... --> +{{ end }} +{{< /code >}} + +If the front matter field of interest is nested beneath another field, you can +also get it: + +{{< code file="layouts/partials/by-nested-param.html" >}} +{{ range (.Pages.ByParam "author.last_name") }} + <!-- ... --> +{{ end }} +{{< /code >}} + +### Reverse Order + +Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example: + +{{< code file="layouts/partials/by-date-reverse.html" >}} +{{ range .Pages.ByDate.Reverse }} +<li> +<a href="{{ .Permalink }}">{{ .Title }}</a> +<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> +</li> +{{ end }} +{{< /code >}} + +## Group Content + +Hugo provides some functions for grouping pages by Section, Type, Date, etc. + +### By Page Field + +{{< code file="layouts/partials/by-page-field.html" >}} +{{ range .Pages.GroupBy "Section" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### By Page date + +{{< code file="layouts/partials/by-page-date.html" >}} +{{ range .Pages.GroupByDate "2006-01" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### By Page publish date + +{{< code file="layouts/partials/by-page-publish-date.html" >}} +{{ range .Pages.GroupByPublishDate "2006-01" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### By Page Param + +{{< code file="layouts/partials/by-page-param.html" >}} +{{ range .Pages.GroupByParam "param_key" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### By Page Param in Date Format + +{{< code file="layouts/partials/by-page-param-as-date.html" >}} +{{ range .Pages.GroupByParamDate "param_key" "2006-01" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +### Reverse Key Order + +The ordering of the groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (newest first) for dates. + +While these are logical defaults, they are not always the desired order. There are two different syntaxes to change the order, both of which work the same way. You can use your preferred syntax. + +#### Reverse Method + +``` +{{ range (.Pages.GroupBy "Section").Reverse }} +``` + +``` +{{ range (.Pages.GroupByDate "2006-01").Reverse }} +``` + + +#### Provide the Alternate Direction + +``` +{{ range .Pages.GroupByDate "2006-01" "asc" }} +``` + +``` +{{ range .Pages.GroupBy "Section" "desc" }} +``` + +### Order Within Groups + +Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available. + +In the following example, groups are ordered chronologically and then content +within each group is ordered alphabetically by title. + +{{< code file="layouts/partials/by-group-by-page.html" >}} +{{ range .Pages.GroupByDate "2006-01" "asc" }} +<h3>{{ .Key }}</h3> +<ul> + {{ range .Pages.ByTitle }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> + </li> + {{ end }} +</ul> +{{ end }} +{{< /code >}} + +## Filter and Limiting Lists + +See the [_Lists/Filtering and Limiting Lists_ +section][filteringandlimitinglists] for details. + + +[views]: /templates/views/ +[filteringandlimitinglists]: /templates/lists/#filtering-and-limiting-lists diff --git a/exampleSite/content/en/documentation/explanation/templates/output-formats.md b/exampleSite/content/en/documentation/explanation/templates/output-formats.md new file mode 100644 index 0000000..fcb66ee --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/output-formats.md @@ -0,0 +1,254 @@ +--- +title: Custom Output Formats +linktitle: Custom Output Formats +description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format. +date: 2017-03-22 +publishdate: 2017-03-22 +lastmod: 2019-12-11 +categories: [templates] +keywords: ["amp","outputs","rss"] + +weight: 18 +sections_weight: 18 +draft: false +aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/] +toc: true +--- + +This page describes how to properly configure your site with the media types and output formats, as well as where to create your templates for your custom outputs. + +## Media Types + +A [media type][] (also known as *MIME type* and *content type*) is a two-part identifier for file formats and format contents transmitted on the Internet. + +This is the full set of built-in media types in Hugo: + +{{< datatable "media" "types" "type" "suffixes" >}} + +**Note:** + +* It is possible to add custom media types or change the defaults; e.g., if you want to change the suffix for `text/html` to `asp`. +* `Suffixes` are the values that will be used for URLs and filenames for that media type in Hugo. +* The `Type` is the identifier that must be used when defining new/custom `Output Formats` (see below). +* The full set of media types will be registered in Hugo's built-in development server to make sure they are recognized by the browser. + +To add or modify a media type, define it in a `mediaTypes` section in your [site configuration][config], either for all sites or for a given language. + +{{< code-toggle file="config" >}} +[mediaTypes] + [mediaTypes."text/enriched"] + suffixes = ["enr"] + [mediaTypes."text/html"] + suffixes = ["asp"] +{{</ code-toggle >}} + +The above example adds one new media type, `text/enriched`, and changes the suffix for the built-in `text/html` media type. + +**Note:** these media types are configured for **your output formats**. If you want to redefine one of Hugo's default output formats (e.g. `HTML`), you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`: + +```toml +[mediaTypes] +[mediaTypes."text/html"] +suffixes = ["htm"] + +# Redefine HTML to update its media type. +[outputFormats] +[outputFormats.HTML] +mediaType = "text/html" +``` + +**Note** that for the above to work, you also need to add an `outputs` definition in your site config. + +## Output Format Definitions + +Given a media type and some additional configuration, you get an **Output Format**. + +This is the full set of Hugo's built-in output formats: + +{{< datatable "output" "formats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly" "permalinkable" >}} + +* A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `AMP` vs. `HTML`. `AMP` has the value `amp` for `Path` so it doesn't overwrite the `HTML` version; e.g. we can now have both `/index.html` and `/amp/index.html`. +* The `MediaType` must match the `Type` of an already defined media type. +* You can define new output formats or redefine built-in output formats; e.g., if you want to put `AMP` pages in a different path. + +To add or modify an output format, define it in an `outputFormats` section in your site's [configuration file](/getting-started/configuration/), either for all sites or for a given language. + +{{< code-toggle file="config" >}} +[outputFormats.MyEnrichedFormat] +mediaType = "text/enriched" +baseName = "myindex" +isPlainText = true +protocol = "bep://" +{{</ code-toggle >}} + +The above example is fictional, but if used for the homepage on a site with `baseURL` `https://example.org`, it will produce a plain text homepage with the URL `bep://example.org/myindex.enr`. + +### Configure Output Formats + +The following is the full list of configuration options for output formats and their default values: + +`name` +: the output format identifier. This is used to define what output format(s) you want for your pages. + +`mediaType` +: this must match the `Type` of a defined media type. + +`path` +: sub path to save the output files. + +`baseName` +: the base filename for the list filenames (homepage, etc.). **Default:** `index`. + +`rel` +: can be used to create `rel` values in `link` tags. **Default:** `alternate`. + +`protocol` +: will replace the "http://" or "https://" in your `baseURL` for this output format. + +`isPlainText` +: use Go's plain text templates parser for the templates. **Default:** `false`. + +`isHTML` +: used in situations only relevant for `HTML`-type formats; e.g., page aliases. + +`noUgly` +: used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **Default:** `false`. + +`notAlternative` +: enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term *alternative* and not *alternate* here, as it does not necessarily replace the other format. **Default:** `false`. + +`permalinkable` +: make `.Permalink` and `.RelPermalink` return the rendering Output Format rather than main ([see below](#link-to-output-formats)). This is enabled by default for `HTML` and `AMP`. **Default:** `false`. + +## Output Formats for Pages + +A `Page` in Hugo can be rendered to multiple *output formats* on the file +system. + +### Default Output Formats +Every `Page` has a [`Kind`][page_kinds] attribute, and the default Output +Formats are set based on that. + +| Kind | Default Output Formats | +|--------------- |----------------------- | +| `page` | HTML | +| `home` | HTML, RSS | +| `section` | HTML, RSS | +| `taxonomy` | HTML, RSS | +| `term` | HTML, RSS | + +### Customizing Output Formats + +This can be changed by defining an `outputs` list of output formats in either +the `Page` front matter or in the site configuration (either for all sites or +per language). + +Example from site config file: + +{{< code-toggle file="config" >}} +[outputs] + home = ["HTML", "AMP", "RSS"] + page = ["HTML"] +{{</ code-toggle >}} + + +Note that in the above examples, the *output formats* for `section`, +`taxonomy` and `term` will stay at their default value `["HTML", +"RSS"]`. + +{{< new-in "0.73.0" >}} We have fixed the before confusing page kinds used for taxonomies (see the listing below) to be in line with the terms used when we talk about taxonomies. We have been careful to avoid site breakage, and you should get an ERROR in the console if you need to adjust your `outputs` section. + +{{% page-kinds %}} + +* The `outputs` definition is per [`Page` `Kind`][page_kinds] (`page`, `home`, `section`, `taxonomy`, or `term`). +* The names (e.g. `HTML`, `AMP`) used must match the `Name` of a defined *Output Format*. + * These names are case insensitive. +* These can be overridden per `Page` in the front matter of content files. + +The following is an example of `YAML` front matter in a content file that defines output formats for the rendered `Page`: + +```yaml +--- +date: "2016-03-19" +outputs: +- html +- amp +- json +--- +``` + +## List Output formats + +Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`: + +```go-html-template +{{ range .AlternativeOutputFormats -}} +<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}"> +{{ end -}} +``` + +## Link to Output Formats + +`.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template file they are being called from. + +__from `single.json.json`:__ +```go-html-template +{{ .RelPermalink }} > /that-page/ +{{ with .OutputFormats.Get "json" -}} +{{ .RelPermalink }} > /that-page/index.json +{{- end }} +``` + +In order for them to return the output format of the current template file instead, the given output format should have its `permalinkable` setting set to true. + +__Same template file as above with json output format's `permalinkable` set to true:__ + +```go-html-template +{{ .RelPermalink }} > /that-page/index.json +{{ with .OutputFormats.Get "html" -}} +{{ .RelPermalink }} > /that-page/ +{{- end }} +``` + +From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref): + +```go-html-template +[Neat]({{</* ref "blog/neat.md" "amp" */>}}) +[Who]({{</* relref "about.md#who" "amp" */>}}) +``` + +## Templates for Your Output Formats + +A new output format needs a corresponding template in order to render anything useful. + +{{% note %}} +The key distinction for Hugo versions 0.20 and newer is that Hugo looks at an output format's `Name` and MediaType's `Suffixes` when choosing the template used to render a given `Page`. +{{% /note %}} + +The following table shows examples of different output formats, the suffix used, and Hugo's respective template [lookup order][]. All of the examples in the table can: + +* Use a [base template][base]. +* Include [partial templates][partials] + +{{< datatable "output" "layouts" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +Hugo will now also detect the media type and output format of partials, if possible, and use that information to decide if the partial should be parsed as a plain text template or not. + +Hugo will look for the name given, so you can name it whatever you want. But if you want it treated as plain text, you should use the file suffix and, if needed, the name of the Output Format. The pattern is as follows: + +``` +[partial name].[OutputFormat].[suffix] +``` + +The partial below is a plain text template (Output Format is `CSV`, and since this is the only output format with the suffix `csv`, we don't need to include the Output Format's `Name`): + +``` +{{ partial "mytextpartial.csv" . }} +``` + +[base]: /templates/base/ +[config]: /getting-started/configuration/ +[lookup order]: /templates/lookup/ +[media type]: https://en.wikipedia.org/wiki/Media_type +[partials]: /templates/partials/ +[page_kinds]: /templates/section-templates/#page-kinds diff --git a/exampleSite/content/en/documentation/explanation/templates/pagination.md b/exampleSite/content/en/documentation/explanation/templates/pagination.md new file mode 100644 index 0000000..26d318a --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/pagination.md @@ -0,0 +1,158 @@ +--- +title: Pagination +linktitle: Pagination +description: Hugo supports pagination for your homepage, section pages, and taxonomies. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [lists,sections,pagination] + +weight: 140 +sections_weight: 140 +draft: false +aliases: [/extras/pagination,/doc/pagination/] +toc: true +--- + +The real power of Hugo pagination shines when combined with the [`where` function][where] and its SQL-like operators: [`first`][], [`last`][], and [`after`][]. You can even [order the content][lists] the way you've become used to with Hugo. + +## Configure Pagination + +Pagination can be configured in your [site configuration][configuration]: + +`Paginate` +: default = `10`. This setting can be overridden within the template. + +`PaginatePath` +: default = `page`. Allows you to set a different path for your pagination pages. + +Setting `Paginate` to a positive value will split the list pages for the homepage, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and homepage is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below). + +`PaginatePath` is used to adapt the `URL` to the pages in the paginator (the default setting will produce URLs on the form `/page/1/`. + +## List Paginator Pages + +{{% warning %}} +`.Paginator` is provided to help you build a pager menu. This feature is currently only supported on homepage and list pages (i.e., taxonomies and section lists). +{{% /warning %}} + +There are two ways to configure and use a `.Paginator`: + +1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page*. +2. Select another set of pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g. + * `{{ range (.Paginate ( first 50 .Pages.ByTitle )).Pages }}` or + * `{{ range (.Paginate .RegularPagesRecursive).Pages }}`. + +For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created. + +If you call `.Paginator` or `.Paginate` multiple times on the same page, you should ensure all the calls are identical. Once *either* `.Paginator` or `.Paginate` is called while generating a page, its result is cached, and any subsequent similar call will reuse the cached result. This means that any such calls which do not match the first one will not behave as written. + +(Remember that function arguments are eagerly evaluated, so a call like `$paginator := cond x .Paginator (.Paginate .RegularPagesRecursive)` is an example of what you should *not* do. Use `if`/`else` instead to ensure exactly one evaluation.) + +The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page: + +* `{{ range (.Paginator 5).Pages }}` +* `{{ $paginator := .Paginate (where .Pages "Type" "posts") 5 }}` + +It is also possible to use the `GroupBy` functions in combination with pagination: + +``` +{{ range (.Paginate (.Pages.GroupByDate "2006")).PageGroups }} +``` + +## Build the navigation + +The `.Paginator` contains enough information to build a paginator interface. + +The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles): + +``` +{{ template "_internal/pagination.html" . }} +``` + +{{% note "When to Create `.Paginator`" %}} +If you use any filters or ordering functions to create your `.Paginator` *and* you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used. +{{% /note %}} + +The following example shows how to create `.Paginator` before its used: + +``` +{{ $paginator := .Paginate (where .Pages "Type" "posts") }} +{{ template "_internal/pagination.html" . }} +{{ range $paginator.Pages }} + {{ .Title }} +{{ end }} +``` + +Without the `where` filter, the above example is even simpler: + +``` +{{ template "_internal/pagination.html" . }} +{{ range .Paginator.Pages }} + {{ .Title }} +{{ end }} +``` + +If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties: + +`PageNumber` +: The current page's number in the pager sequence + +`URL` +: The relative URL to the current pager + +`Pages` +: The pages in the current pager + +`NumberOfElements` +: The number of elements on this page + +`HasPrev` +: Whether there are page(s) before the current + +`Prev` +: The pager for the previous page + +`HasNext` +: Whether there are page(s) after the current + +`Next` +: The pager for the next page + +`First` +: The pager for the first page + +`Last` +: The pager for the last page + +`Pagers` +: A list of pagers that can be used to build a pagination menu + +`PageSize` +: Size of each pager + +`TotalPages` +: The number of pages in the paginator + +`TotalNumberOfElements` +: The number of elements on all pages in this paginator + +## Additional information + +The pages are built on the following form (`BLANK` means no value): + +``` +[SECTION/TAXONOMY/BLANK]/index.html +[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to [SECTION/TAXONOMY/BLANK]/index.html +[SECTION/TAXONOMY/BLANK]/page/2/index.html +.... +``` + + +[`first`]: /functions/first/ +[`last`]: /functions/last/ +[`after`]: /functions/after/ +[configuration]: /getting-started/configuration/ +[lists]: /templates/lists/ +[where]: /functions/where/ diff --git a/exampleSite/content/en/documentation/explanation/templates/partials.md b/exampleSite/content/en/documentation/explanation/templates/partials.md new file mode 100644 index 0000000..5327dcf --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/partials.md @@ -0,0 +1,204 @@ +--- +title: Partial Templates +linktitle: Partial Templates +description: Partials are smaller, context-aware components in your list and page templates that can be used economically to keep your templating DRY. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [lists,sections,partials] + +weight: 90 +sections_weight: 90 +draft: false +aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/] +toc: true +--- + +{{< youtube pjS4pOLyB7c >}} + +## Partial Template Lookup Order + +Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order][]. However, partials are simpler in that Hugo will only check in two places: + +1. `layouts/partials/*<PARTIALNAME>.html` +2. `themes/<THEME>/layouts/partials/*<PARTIALNAME>.html` + +This allows a theme's end user to copy a partial's contents into a file of the same name for [further customization][customize]. + +## Use Partials in your Templates + +All partials for your Hugo project are located in a single `layouts/partials` directory. For better organization, you can create multiple subdirectories within `partials` as well: + +``` +. +└── layouts + └── partials + ├── footer + │ ├── scripts.html + │ └── site-footer.html + ├── head + │ ├── favicons.html + │ ├── metadata.html + │ ├── prerender.html + │ └── twitter.html + └── header + ├── site-header.html + └── site-nav.html +``` + +All partials are called within your templates using the following pattern: + +``` +{{ partial "<PATH>/<PARTIAL>.html" . }} +``` + +{{% note %}} +One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/). +{{% /note %}} + +{{% note %}} +`<PARTIAL>` including `baseof` is reserved. ([#5373](https://github.com/gohugoio/hugo/issues/5373)) +{{% /note %}} + +As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory: + +``` +{{ partial "header/site-header.html" . }} +{{ partial "footer/scripts.html" . }} +``` + +### Variable Scoping + +The second argument in a partial call is the variable being passed down. The above examples are passing the `.`, which tells the template receiving the partial to apply the current [context][context]. + +This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`. + +## Returning a value from a Partial + +In addition to outputting markup, partials can be used to return a value of any type. In order to return a value, a partial must include a lone `return` statement. + +## Inline partials + +{{< new-in "0.74.0" >}} + +You can also define partials inline in the template. But remember that template namespace is global, so you need to make sure that the names are unique to avoid conflicts. + +```go-html-template +Value: {{ partial "my-inline-partial" . }} + +{{ define "partials/my-inline-partial" }} +{{ $value := 32 }} +{{ return $value }} +{{ end }} +``` + +### Example GetFeatured +```go-html-template +{{/* layouts/partials/GetFeatured.html */}} +{{ return first . (where site.RegularPages ".Params.featured" true) }} +``` + +```go-html-template +{{/* layouts/index.html */}} +{{ range partial "GetFeatured.html" 5 }} + [...] +{{ end }} +``` +### Example GetImage +```go-html-template +{{/* layouts/partials/GetImage.html */}} +{{ $image := false }} +{{ with .Params.gallery }} + {{ $image = index . 0 }} +{{ end }} +{{ with .Params.image }} + {{ $image = . }} +{{ end }} +{{ return $image }} +``` + +```go-html-template +{{/* layouts/_default/single.html */}} +{{ with partial "GetImage.html" . }} + [...] +{{ end }} +``` + +{{% note %}} +Only one `return` statement is allowed per partial file. +{{% /note %}} + +## Cached Partials + +The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows: + +``` +{{ partialCached "footer.html" . }} +``` + +You can also pass additional parameters to `partialCached` to create *variants* of the cached partial. + +For example, you can tell Hugo to only render the partial `footer.html` once per section: + +``` +{{ partialCached "footer.html" . .Section }} +``` + +If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need: + +``` +{{ partialCached "footer.html" . .Params.country .Params.province }} +``` + +Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key. + +### Example `header.html` + +The following `header.html` partial template is used for [spf13.com](https://spf13.com/): + +{{< code file="layouts/partials/header.html" download="header.html" >}} +<!DOCTYPE html> +<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#"> +<head> + <meta charset="utf-8"> + + {{ partial "meta.html" . }} + + <base href="{{ .Site.BaseURL }}"> + <title> {{ .Title }} : spf13.com </title> + <link rel="canonical" href="{{ .Permalink }}"> + {{ if .RSSLink }}<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }} + + {{ partial "head_includes.html" . }} +</head> +<body lang="en"> +{{< /code >}} + +{{% note %}} +The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility. +{{% /note %}} + +### Example `footer.html` + +The following `footer.html` partial template is used for [spf13.com](https://spf13.com/): + +{{< code file="layouts/partials/footer.html" download="footer.html" >}} +<footer> + <div> + <p> + © 2013-14 Steve Francia. + <a href="https://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>; + please attribute properly and link back. + </p> + </div> +</footer> +{{< /code >}} + +[context]: /templates/introduction/ "The most easily overlooked concept to understand about Go templating is how the dot always refers to the current context." +[customize]: /themes/customizing/ "Hugo provides easy means to customize themes as long as users are familiar with Hugo's template lookup order." +[listtemps]: /templates/lists/ "To effectively leverage Hugo's system, see how Hugo handles list pages, where content for sections, taxonomies, and the homepage are listed and ordered." +[lookup order]: /templates/lookup-order/ "To keep your templating dry, read the documentation on Hugo's lookup order." +[partialcached]: /functions/partialcached/ "Use the partial cached function to improve build times in cases where Hugo can cache partials that don't need to be rendered with every page." +[singletemps]: /templates/single-page-templates/ "The most common form of template in Hugo is the single content template. Read the docs on how to create templates for individual pages." +[themes]: /themes/ diff --git a/exampleSite/content/en/documentation/explanation/templates/robots.md b/exampleSite/content/en/documentation/explanation/templates/robots.md new file mode 100644 index 0000000..e953dd5 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/robots.md @@ -0,0 +1,51 @@ +--- +title: Robots.txt File +linktitle: Robots.txt +description: Hugo can generate a customized robots.txt in the same way as any other template. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [robots,search engines] + +weight: 165 +sections_weight: 165 +draft: false +aliases: [/extras/robots-txt/] +toc: false +--- + +To create your robots.txt as a template, first set the `enableRobotsTXT` value to `true` in your [configuration file][config]. By default, this option generates a robots.txt with the following content, which tells search engines that they are allowed to crawl everything: + +``` +User-agent: * +``` + +## Robots.txt Template Lookup Order + +The [lookup order][lookup] for the `robots.txt` template is as follows: + +* `/layouts/robots.txt` +* `/themes/<THEME>/layouts/robots.txt` + +{{% note %}} +If you do not want Hugo to create a default `robots.txt` or leverage the `robots.txt` template, you can hand code your own and place the file in `static`. Remember that everything in the [static directory](/getting-started/directory-structure/) is copied over as-is when Hugo builds your site. +{{% /note %}} + +## Robots.txt Template Example + +The following is an example `robots.txt` layout: + +{{< code file="layouts/robots.txt" download="robots.txt" >}} +User-agent: * + +{{range .Pages}} +Disallow: {{.RelPermalink}} +{{end}} +{{< /code >}} + +This template disallows all the pages of the site by creating one `Disallow` entry for each page. + +[config]: /getting-started/configuration/ +[lookup]: /templates/lookup-order/ +[robots]: https://www.robotstxt.org/ diff --git a/exampleSite/content/en/documentation/explanation/templates/rss.md b/exampleSite/content/en/documentation/explanation/templates/rss.md new file mode 100644 index 0000000..8e27819 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/rss.md @@ -0,0 +1,89 @@ +--- +title: RSS Templates +linktitle: RSS Templates +description: Hugo ships with its own RSS 2.0 template that requires almost no configuration, or you can create your own RSS templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +keywords: [rss, xml, templates] +categories: [templates] + +weight: 150 +sections_weight: 150 +draft: false +toc: true +--- + +## RSS Template Lookup Order + +See [Template Lookup Order](/templates/lookup-order/) for the complete reference. + +{{% note "Hugo Ships with an RSS Template" %}} +Hugo ships with its own [RSS 2.0 template](#the-embedded-rssxml). The embedded template will be sufficient for most use cases. +{{% /note %}} + +RSS pages are of the type `Page` and have all the [page variables](/variables/page/) available to use in the templates. + +### Section RSS + +A [section’s][section] RSS will be rendered at `/<SECTION>/index.xml` (e.g., [https://spf13.com/project/index.xml](https://spf13.com/project/index.xml)). + +Hugo provides the ability for you to define any RSS type you wish and can have different RSS files for each section and taxonomy. + +## Lookup Order for RSS Templates + +The table below shows the RSS template lookup order for the different page kinds. The first listing shows the lookup order when running with a theme (`demoTheme`). + +{{< datatable-filtered "output" "layouts" "OutputFormat == RSS" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Configure RSS + +By default, Hugo will create an unlimited number of RSS entries. You can limit the number of articles included in the built-in RSS templates by assigning a numeric value to `rssLimit:` field in your project's [`config` file][config]. + +The following values will also be included in the RSS output if specified in your site’s configuration: + +```toml +languageCode = "en-us" +copyright = "This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License." + +[author] + name = "My Name Here" +``` + +## The Embedded rss.xml + +This is the default RSS template that ships with Hugo: + +https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml + +## Reference your RSS Feed in `<head>` + +In your `header.html` template, you can specify your RSS feed in your `<head></head>` tag using Hugo's [Output Formats][Output Formats] like this: + +```go-html-template +{{ range .AlternativeOutputFormats -}} + {{ printf `<link rel="%s" type="%s" href="%s" title="%s" />` .Rel .MediaType.Type .Permalink $.Site.Title | safeHTML }} +{{ end -}} +``` + +If you only want the RSS link, you can query the formats: + +```go-html-template +{{ with .OutputFormats.Get "rss" -}} + {{ printf `<link rel="%s" type="%s" href="%s" title="%s" />` .Rel .MediaType.Type .Permalink $.Site.Title | safeHTML }} +{{ end -}} +``` + +Either of the two snippets above will generate the below `link` tag on the site homepage for RSS output: + +```html +<link rel="alternate" type="application/rss+xml" href="https://example.com/index.xml" title="Site Title"> +``` + +_We are assuming `BaseURL` to be `https://example.com/` and `$.Site.Title` to be `"Site Title"` in this example._ + +[config]: /getting-started/configuration/ +[embedded]: #the-embedded-rss-xml +[RSS 2.0]: https://cyber.harvard.edu/rss/rss.html "RSS 2.0 Specification" +[section]: /content-management/sections/ +[Output Formats]: /templates/output-formats/#link-to-output-formats diff --git a/exampleSite/content/en/documentation/explanation/templates/section-templates.md b/exampleSite/content/en/documentation/explanation/templates/section-templates.md new file mode 100644 index 0000000..f6890db --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/section-templates.md @@ -0,0 +1,113 @@ +--- +title: Section Page Templates +linktitle: Section Templates +description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [lists,sections,templates] + +weight: 40 +sections_weight: 40 +draft: false +aliases: [/templates/sections/] +toc: true +--- + +## Add Content and Front Matter to Section Templates + +To effectively leverage section page templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages. + +## Section Template Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +## Page Kinds + +Every `Page` in Hugo has a `.Kind` attribute. + +{{% page-kinds %}} + +## `.Site.GetPage` with Sections + +`Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path. + +The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`. + +You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values +of `Kind` from above) and `kind value`. + +Examples: + +- `{{ .Site.GetPage "section" "posts" }}` +- `{{ .Site.GetPage "page" "search" }}` + +## Example: Creating a Default Section Template + +{{< code file="layouts/_default/section.html" download="section.html" >}} +{{ define "main" }} + <main> + {{ .Content }} + <ul class="contents"> + {{ range .Paginator.Pages }} + <li>{{.Title}} + <div> + {{ partial "summary.html" . }} + </div> + </li> + {{ end }} + </ul> + {{ partial "pagination.html" . }} + </main> +{{ end }} +{{< /code >}} + +### Example: Using `.Site.GetPage` + +The `.Site.GetPage` example that follows assumes the following project directory structure: + +``` +. +└── content + ├── blog + │ ├── _index.md # "title: My Hugo Blog" in the front matter + │ ├── post-1.md + │ ├── post-2.md + │ └── post-3.md + └── events #Note there is no _index.md file in "events" + ├── event-1.md + └── event-2.md +``` + +`.Site.GetPage` will return `nil` if no `_index.md` page is found. Therefore, if `content/blog/_index.md` does not exist, the template will output the section name: + +``` +<h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1> +``` + +Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result: + +``` +<h1>My Hugo Blog</h1> +``` + +If we try the same code with the `events` section, however, Hugo will default to the section title because there is no `content/events/_index.md` from which to pull content and front matter: + +``` +<h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1> +``` + +Which then returns the following: + +``` +<h1>Events</h1> +``` + + +[contentorg]: /content-management/organization/ +[getpage]: /functions/getpage/ +[lists]: /templates/lists/ +[lookup]: /templates/lookup-order/ +[where]: /functions/where/ +[sections]: /content-management/sections/ diff --git a/exampleSite/content/en/documentation/explanation/templates/shortcode-templates.md b/exampleSite/content/en/documentation/explanation/templates/shortcode-templates.md new file mode 100644 index 0000000..5c71f24 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/shortcode-templates.md @@ -0,0 +1,411 @@ +--- +title: Create Your Own Shortcodes +linktitle: Shortcode Templates +description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [shortcodes,templates] + +weight: 100 +sections_weight: 100 +draft: false +aliases: [] +toc: true +--- + +Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside of your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][]. + +{{% note %}} +Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).) +{{% /note %}} + +## Create Custom Shortcodes + +Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs. + +{{< youtube Eu4zSaKOY4A >}} + +### File Location + +To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose. + +You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g: + +``` +{{</* boxes/square */>}} +``` + +Note the forward slash. + +### Shortcode Template Lookup Order + +Shortcode templates have a simple [lookup order][]: + +1. `/layouts/shortcodes/<SHORTCODE>.html` +2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html` + +### Positional vs Named Parameters + +You can create shortcodes using the following types of parameters: + +* Positional parameters +* Named parameters +* Positional *or* named parameters (i.e, "flexible") + +In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors. + +For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order. + +Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users. + +### Access Parameters + +All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively. + +To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string: + +``` +{{ .Get "class" }} +``` + +To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed: + +``` +{{ .Get 0 }} +``` + +For the second position, you would just use: + +``` +{{ .Get 1 }} +``` + +`with` is great when the output depends on a parameter being set: + +``` +{{ with .Get "class"}} class="{{.}}"{{ end }} +``` + +`.Get` can also be used to check if a parameter has been provided. This is +most helpful when the condition depends on either of the values, or both: + +``` +{{ if or (.Get "title") (.Get "alt") }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }} +``` + +#### `.Inner` + +If a closing shortcode is used, the `.Inner` variable will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` as an indicator of its existence. + +A shortcode with content declared via the `.Inner` variable can also be declared without the inline content and without the closing shortcode by using the self-closing syntax: + +``` +{{</* innershortcode /*/>}} +``` + +#### `.Params` + +The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic: + +`$.Params` +: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID) + +`$.Page.Params` +: refers to the page's params; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`). + +`$.Page.Site.Params` +: refers to global variables as defined in your [site's configuration file][config]. + +#### `.IsNamedParams` + +The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value. + +For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows: + +``` +{{</* image src="images/my-image.jpg"*/>}} +``` + +You could then include the following as part of your shortcode templating: + +``` +{{ if .IsNamedParams }} +<img src="{{.Get "src" }}" alt=""> +{{ else }} +<img src="{{.Get 0}}" alt=""> +{{ end }} +``` + +See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action. + +{{% warning %}} +While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error. +{{% /warning %}} + +You can also use the variable `.Page` to access all the normal [page variables][pagevars]. + +A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root. + +### Checking for Existence + +You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode. + +## Custom Shortcode Examples + +The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`. + +### Single-word Example: `year` + +Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows: + +``` +{{</* year */>}} +``` + +{{< code file="/layouts/shortcodes/year.html" >}} +{{ now.Format "2006" }} +{{< /code >}} + +### Single Positional Example: `youtube` + +Embedded videos are a common addition to markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]: + +``` +{{</* youtube 09jf3ow9jfw */>}} +``` + +Would load the template at `/layouts/shortcodes/youtube.html`: + +{{< code file="/layouts/shortcodes/youtube.html" >}} +<div class="embed video-player"> +<iframe class="youtube-player" type="text/html" width="640" height="385" src="https://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0"> +</iframe> +</div> +{{< /code >}} + +{{< code file="youtube-embed.html" copy="false" >}} +<div class="embed video-player"> + <iframe class="youtube-player" type="text/html" + width="640" height="385" + src="https://www.youtube.com/embed/09jf3ow9jfw" + allowfullscreen frameborder="0"> + </iframe> +</div> +{{< /code >}} + +### Single Named Example: `image` + +Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files: + +{{< code file="content-image.md" >}} +{{</* img src="/media/spf13.jpg" title="Steve Francia" */>}} +{{< /code >}} + +You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: + +{{< code file="/layouts/shortcodes/img.html" >}} +<!-- image --> +<figure {{ with .Get "class" }}class="{{.}}"{{ end }}> + {{ with .Get "link"}}<a href="{{.}}">{{ end }} + <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} /> + {{ if .Get "link"}}</a>{{ end }} + {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}} + <figcaption>{{ if isset .Params "title" }} + <h4>{{ .Get "title" }}</h4>{{ end }} + {{ if or (.Get "caption") (.Get "attr")}}<p> + {{ .Get "caption" }} + {{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }} + {{ .Get "attr" }} + {{ if .Get "attrlink"}}</a> {{ end }} + </p> {{ end }} + </figcaption> + {{ end }} +</figure> +<!-- image --> +{{< /code >}} + +Would be rendered as: + +{{< code file="img-output.html" copy="false" >}} +<figure> + <img src="/media/spf13.jpg" /> + <figcaption> + <h4>Steve Francia</h4> + </figcaption> +</figure> +{{< /code >}} + +### Single Flexible Example: `vimeo` + +``` +{{</* vimeo 49718712 */>}} +{{</* vimeo id="49718712" class="flex-video" */>}} +``` + +Would load the template found at `/layouts/shortcodes/vimeo.html`: + +{{< code file="/layouts/shortcodes/vimeo.html" >}} +{{ if .IsNamedParams }} + <div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}"> + <iframe src="https://player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe> + </div> +{{ else }} + <div class="{{ if len .Params | eq 2 }}{{ .Get 1 }}{{ else }}vimeo-container{{ end }}"> + <iframe src="https://player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe> + </div> +{{ end }} +{{< /code >}} + +Would be rendered as: + +{{< code file="vimeo-iframes.html" copy="false" >}} +<div class="vimeo-container"> + <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe> +</div> +<div class="flex-video"> + <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe> +</div> +{{< /code >}} + +### Paired Example: `highlight` + +The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo. + +{{< code file="highlight-example.md" >}} +{{</* highlight html */>}} + <html> + <body> This HTML </body> + </html> +{{</* /highlight */>}} +{{< /code >}} + +The template for the `highlight` shortcode uses the following code, which is already included in Hugo: + +``` +{{ .Get 0 | highlight .Inner }} +``` + +The rendered output of the HTML example code block will be as follows: + +{{< code file="syntax-highlighted.html" copy="false" >}} +<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span> + <span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span> +<span style="color: #f92672"></html></span> +</pre></div> +{{< /code >}} + +### Nested Shortcode: Image Gallery + +Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending on whether the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters. + +The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter: + +{{< code file="layouts/shortcodes/gallery.html" >}} +<div class="{{.Get "class"}}"> + {{.Inner}} +</div> +{{< /code >}} + +You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`: + +{{< code file="layouts/shortcodes/img.html" >}} +{{- $src := .Get "src" -}} +{{- with .Parent -}} + <img src="{{$src}}" class="{{.Get "class"}}-image"> +{{- else -}} + <img src="{{$src}}"> +{{- end }} +{{< /code >}} + +You can then call your shortcode in your content as follows: + +``` +{{</* gallery class="content-gallery" */>}} + {{</* img src="/images/one.jpg" */>}} + {{</* img src="/images/two.jpg" */>}} +{{</* /gallery */>}} +{{</* img src="/images/three.jpg" */>}} +``` + +This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`: + +``` +<div class="content-gallery"> + <img src="/images/one.jpg" class="content-gallery-image"> + <img src="/images/two.jpg" class="content-gallery-image"> +</div> +<img src="/images/three.jpg"> +``` + + +## Error Handling in Shortcodes + +Use the [errorf](/functions/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes: + +```bash +{{ with .Get "name" }} +{{ else }} +{{ errorf "missing value for param 'name': %s" .Position }} +{{ end }} +``` + +When the above fails, you will see an `ERROR` log similar to the below: + +```bash +ERROR 2018/11/07 10:05:55 missing value for param name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1" +``` + +## More Shortcode Examples + +More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes]. + + +## Inline Shortcodes + +Since Hugo 0.52, you can implement your shortcodes inline -- e.g. where you use them in the content file. This can be useful for scripting that you only need in one place. + +This feature is disabled by default, but can be enabled in your site config: + +{{< code-toggle file="config">}} +enableInlineShortcodes = true +{{< /code-toggle >}} + +It is disabled by default for security reasons. The security model used by Hugo's template handling assumes that template authors are trusted, but that the content files are not, so the templates are injection-safe from malformed input data. But in most situations you have full control over the content, too, and then `enableInlineShortcodes = true` would be considered safe. But it's something to be aware of: It allows ad-hoc [Go Text templates](https://golang.org/pkg/text/template/) to be executed from the content files. + +And once enabled, you can do this in your content files: + + ```go-text-template + {{</* time.inline */>}}{{ now }}{{</* /time.inline */>}} + ``` + +The above will print the current date and time. + + Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template. + +This means that the current page can be accessed via `.Page.Title` etc. This also means that there are no concept of "nested inline shortcodes". + +The same inline shortcode can be reused later in the same content file, with different params if needed, using the self-closing syntax: + + ```go-text-template +{{</* time.inline /*/>}} +``` + + +[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website." +[built-in shortcode]: /content-management/shortcodes/ +[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website." +[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files." +[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories." +[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading." +[figure]: /content-management/shortcodes/#figure +[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes +[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time" +[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates." +[parent]: /variables/shortcodes/ +[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template." +[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia." +[templates]: /templates/ "The templates section of the Hugo docs." +[vimeoexample]: #single-flexible-example-vimeo +[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode." diff --git a/exampleSite/content/en/documentation/explanation/templates/single-page-templates.md b/exampleSite/content/en/documentation/explanation/templates/single-page-templates.md new file mode 100644 index 0000000..824be62 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/single-page-templates.md @@ -0,0 +1,89 @@ +--- +title: Single Page Templates +linktitle: +description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-04-06 +categories: [templates] +keywords: [page,templates] + +weight: 60 +sections_weight: 60 +draft: false +aliases: [/layout/content/] +toc: true +--- + +## Single Page Template Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +## Example Single Page Templates + +Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates. + +### `posts/single.html` + +This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter. + +{{< code file="layouts/posts/single.html" download="single.html" >}} +{{ define "main" }} +<section id="main"> + <h1 id="title">{{ .Title }}</h1> + <div> + <article id="content"> + {{ .Content }} + </article> + </div> +</section> +<aside id="meta"> + <div> + <section> + <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4> + <h5 id="wordcount"> {{ .WordCount }} Words </h5> + </section> + {{ with .Params.topics }} + <ul id="topics"> + {{ range . }} + <li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li> + {{ end }} + </ul> + {{ end }} + {{ with .Params.tags }} + <ul id="tags"> + {{ range . }} + <li> <a href="{{ "tags" | absURL }}{{ . | urlize }}">{{ . }}</a> </li> + {{ end }} + </ul> + {{ end }} + </div> + <div> + {{ with .PrevInSection }} + <a class="previous" href="{{.Permalink}}"> {{.Title}}</a> + {{ end }} + {{ with .NextInSection }} + <a class="next" href="{{.Permalink}}"> {{.Title}}</a> + {{ end }} + </div> +</aside> +{{ end }} +{{< /code >}} + +To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes]. + +[archetypes]: /content-management/archetypes/ +[base templates]: /templates/base/ +[config]: /getting-started/configuration/ +[content type]: /content-management/types/ +[directory structure]: /getting-started/directory-structure/ +[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself +[`.Format` function]: /functions/format/ +[front matter]: /content-management/front-matter/ +[pagetaxonomy]: /templates/taxonomy-templates/#displaying-a-single-piece-of-content-s-taxonomies +[pagevars]: /variables/page/ +[partials]: /templates/partials/ +[section]: /content-management/sections/ +[site variables]: /variables/site/ +[spf13]: https://spf13.com/ +[`with`]: /functions/with/ diff --git a/exampleSite/content/en/documentation/explanation/templates/sitemap-template.md b/exampleSite/content/en/documentation/explanation/templates/sitemap-template.md new file mode 100644 index 0000000..411bfa5 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/sitemap-template.md @@ -0,0 +1,103 @@ +--- +title: Sitemap Template +# linktitle: Sitemap +description: Hugo ships with a built-in template file observing the v0.9 of the Sitemap Protocol, but you can override this template if needed. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [sitemap, xml, templates] + +weight: 160 +sections_weight: 160 +draft: false +aliases: [/layout/sitemap/,/templates/sitemap/] +toc: false +--- + +A single Sitemap template is used to generate the `sitemap.xml` file. +Hugo automatically comes with this template file. *No work is needed on +the users' part unless they want to customize `sitemap.xml`.* + +A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use in this template along with Sitemap-specific ones: + +`.Sitemap.ChangeFreq` +: The page change frequency + +`.Sitemap.Priority` +: The priority of the page + +`.Sitemap.Filename` +: The sitemap filename + +If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo. + +## Sitemap Templates + +Hugo has built-on Sitemap templates, but you can provide your own if needed, in either `layouts/sitemap.xml` or `layouts/_default/sitemap.xml`. + +For multilingual sites, we also create a Sitemap index. You can provide a custom layout for that in either `layouts/sitemapindex.xml` or `layouts/_default/sitemapindex.xml`. + +## Hugo’s sitemap.xml + +This template respects the version 0.9 of the [Sitemap Protocol](https://www.sitemaps.org/protocol.html). + +```xml +{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }} +<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" + xmlns:xhtml="http://www.w3.org/1999/xhtml"> + {{ range .Data.Pages }} + <url> + <loc>{{ .Permalink }}</loc>{{ if not .Lastmod.IsZero }} + <lastmod>{{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ end }}{{ with .Sitemap.ChangeFreq }} + <changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }} + <priority>{{ .Sitemap.Priority }}</priority>{{ end }}{{ if .IsTranslated }}{{ range .Translations }} + <xhtml:link + rel="alternate" + hreflang="{{ .Lang }}" + href="{{ .Permalink }}" + />{{ end }} + <xhtml:link + rel="alternate" + hreflang="{{ .Lang }}" + href="{{ .Permalink }}" + />{{ end }} + </url> + {{ end }} +</urlset> +``` + +## Hugo's sitemapindex.xml + +This is used to create a Sitemap index in multilingual mode: + +```xml +{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }} +<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> + {{ range . }} + <sitemap> + <loc>{{ .SitemapAbsURL }}</loc> + {{ if not .LastChange.IsZero }} + <lastmod>{{ .LastChange.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod> + {{ end }} + </sitemap> + {{ end }} +</sitemapindex> +``` + +## Configure `sitemap.xml` + +Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in the site's config file, e.g.: + +{{< code-toggle file="config" >}} +[sitemap] + changefreq = "monthly" + priority = 0.5 + filename = "sitemap.xml" +{{</ code-toggle >}} + +The same fields can be specified in an individual content file's front matter in order to override the value assigned to that piece of content at render time. + + + +[pagevars]: /variables/page/ diff --git a/exampleSite/content/en/documentation/explanation/templates/taxonomy-templates.md b/exampleSite/content/en/documentation/explanation/templates/taxonomy-templates.md new file mode 100644 index 0000000..298bafc --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/taxonomy-templates.md @@ -0,0 +1,338 @@ +--- +title: Taxonomy Templates +# linktitle: +description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [taxonomies,metadata,front matter,terms,templates] + +weight: 50 +sections_weight: 50 +draft: false +aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/] +toc: true +--- + +<!-- NOTE! Check on https://github.com/gohugoio/hugo/issues/2826 for shifting of terms' pages to .Data.Pages AND +https://discourse.gohugo.io/t/how-to-specify-category-slug/4856/15 for original discussion.--> + +Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature. + +Hugo provides multiple ways to use taxonomies throughout your project templates: + +* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-template) +* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-template) +* List a single content's taxonomy terms within a [single page template][] + +## Taxonomy List Templates + +Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists]. + +### Taxonomy List Template Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +## Taxonomy Terms Template + +### Taxonomy Terms Templates Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +### Taxonomy Methods + +A Taxonomy is a `map[string]WeightedPages`. + +.Get(term) +: Returns the WeightedPages for a term. + +.Count(term) +: The number of pieces of content assigned to this term. + +.Alphabetical +: Returns an OrderedTaxonomy (slice) ordered by Term. + +.ByCount +: Returns an OrderedTaxonomy (slice) ordered by number of entries. + +.Reverse +: Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy. + +### OrderedTaxonomy + +Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order. + +```go +[]struct { + Name string + WeightedPages WeightedPages +} +``` + +Each element of the slice has: + +.Term +: The Term used. + +.WeightedPages +: A slice of Weighted Pages. + +.Count +: The number of pieces of content assigned to this term. + +.Pages +: All Pages assigned to this term. All [list methods][renderlists] are available to this. + +## WeightedPages + +WeightedPages is simply a slice of WeightedPage. + +```go +type WeightedPages []WeightedPage +``` + +.Count(term) +: The number of pieces of content assigned to this term. + +.Pages +: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists]. + +## Displaying custom metadata in Taxonomy Terms Templates + +If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such: + +```go-html-template +<ul> + {{ range .Pages }} + <li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + {{ .Params.wikipedia }} + </li> + {{ end }} +</ul> +``` + +<!-- Begin /taxonomies/ordering/ --> + +## Order Taxonomies + +Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key. + +### Order Alphabetically Example + +```go-html-template +<ul> + {{ range .Data.Terms.Alphabetical }} + <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li> + {{ end }} +</ul> +``` + +<!-- [See Also Taxonomy Lists](/templates/list/) --> + +## Order Content within Taxonomies + +Hugo uses both `date` and `weight` to order content within taxonomies. + +Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to. + +When iterating over content within taxonomies, the default sort is the same as that used for section and list pages: first by weight, then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first. + +The default weight for any piece of content is 0. Zero means "does not have a weight", not "has a weight of numerical value zero". + +Weights of zero are thus treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end. + +### Assign Weight + +Content can be assigned weight for each taxonomy that it's assigned to. + +``` ++++ +tags = [ "a", "b", "c" ] +tags_weight = 22 +categories = ["d"] +title = "foo" +categories_weight = 44 ++++ +Front Matter with weighted tags and categories +``` + +The convention is `taxonomyname_weight`. + +In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy. + +It has also been assigned the weight of 44 when rendering the 'd' category. + +With this the same piece of content can appear in different positions in different taxonomies. + +Currently taxonomies only support the default ordering of content which is weight -> date. + +<!-- Begin /taxonomies/templates/ --> + +There are two different templates that the use of taxonomies will require you to provide. + +Both templates are covered in detail in the templates section. + +A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages. + +A [taxonomy terms template](/templates/terms/) is a template used to +generate the list of terms for a given template. + +<!-- Begin /taxonomies/displaying/ --> + +There are four common ways you can display the data in your +taxonomies in addition to the automatic taxonomy pages created by hugo +using the [list templates](/templates/list/): + +1. For a given piece of content, you can list the terms attached +2. For a given piece of content, you can list other content with the same + term +3. You can list all terms for a taxonomy +4. You can list all taxonomies (with their terms) + +## Display a Single Piece of Content's Taxonomies + +Within your content templates, you may wish to display the taxonomies that piece of content is assigned to. + +Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.<TAXONOMYPLURAL>`). + +### Example: List Tags in a Single Page Template + +```go-html-template +<ul> + {{ range (.GetTerms "tags") }} + <li><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter. + +To list such taxonomies, use the following: + +### Example: Comma-delimit Tags in a Single Page Template + +```go-html-template +{{ $taxo := "directors" }} <!-- Use the plural form here --> +{{ with .Param $taxo }} + <strong>Director{{ if gt (len .) 1 }}s{{ end }}:</strong> + {{ range $index, $director := . }} + {{- if gt $index 0 }}, {{ end -}} + {{ with $.Site.GetPage (printf "/%s/%s" $taxo $director) -}} + <a href="{{ .Permalink }}">{{ $director }}</a> + {{- end -}} + {{- end -}} +{{ end }} +``` + +Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion. + +## List Content with the Same Taxonomy Term + +If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content: + +### Example: Showing Content in Same Series + +```go-html-template +<ul> + {{ range .Site.Taxonomies.series.golang }} + <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li> + {{ end }} +</ul> +``` + +## List All content in a Given taxonomy + +This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content. + +### Example: Grouping "Featured" Content + +```go-html-template +<section id="menu"> + <ul> + {{ range $key, $taxonomy := .Site.Taxonomies.featured }} + <li>{{ $key }}</li> + <ul> + {{ range $taxonomy.Pages }} + <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> + {{ end }} + </ul> +</section> +``` + +## Render a Site's Taxonomies + +If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page. + +This may take the form of a tag cloud, a menu, or simply a list. + +The following example displays all terms in a site's tags taxonomy: + +### Example: List All Site Tags {#example-list-all-site-tags} + +```go-html-template +<ul> + {{ range .Site.Taxonomies.tags }} + <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li> + {{ end }} +</ul> +``` + +### Example: List All Taxonomies, Terms, and Assigned Content + +This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms. + +{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}} +<section> + <ul id="all-taxonomies"> + {{ range $taxonomy_term, $taxonomy := .Site.Taxonomies }} + {{ with $.Site.GetPage (printf "/%s" $taxonomy_term) }} + <li><a href="{{ .Permalink }}">{{ $taxonomy_term }}</a> + <ul> + {{ range $key, $value := $taxonomy }} + <li>{{ $key }}</li> + <ul> + {{ range $value.Pages }} + <li hugo-nav="{{ .RelPermalink}}"> + <a href="{{ .Permalink}}">{{ .LinkTitle }}</a> + </li> + {{ end }} + </ul> + {{ end }} + </ul> + </li> + {{ end }} + {{ end }} + </ul> +</section> +{{< /code >}} + +## `.Site.GetPage` for Taxonomies + +Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above]({{< relref "#example-list-all-site-tags" >}}): + +{{< code file="links-to-all-tags.html" >}} +{{ $taxo := "tags" }} +<ul class="{{ $taxo }}"> + {{ with ($.Site.GetPage (printf "/%s" $taxo)) }} + {{ range .Pages }} + <li><a href="{{ .Permalink }}">{{ .Title}}</a></li> + {{ end }} + {{ end }} +</ul> +{{< /code >}} + +<!-- TODO: ### `.Site.GetPage` Taxonomy List Example --> + +<!-- TODO: ### `.Site.GetPage` Taxonomy Terms Example --> + + +[delimit]: /functions/delimit/ +[getpage]: /functions/getpage/ +[lists]: /templates/lists/ +[renderlists]: /templates/lists/ +[single page template]: /templates/single-page-templates/ +[sitevars]: /variables/site/ diff --git a/exampleSite/content/en/documentation/explanation/templates/template-debugging.md b/exampleSite/content/en/documentation/explanation/templates/template-debugging.md new file mode 100644 index 0000000..c1b58cf --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/template-debugging.md @@ -0,0 +1,74 @@ +--- +title: Template Debugging +# linktitle: Template Debugging +description: You can use Go templates' `printf` function to debug your Hugo templates. These snippets provide a quick and easy visualization of the variables available to you in different contexts. +godocref: https://golang.org/pkg/fmt/ +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [debugging,troubleshooting] + +weight: 180 +sections_weight: 180 +draft: false +aliases: [] +toc: false +--- + +Here are some snippets you can add to your template to answer some common questions. + +These snippets use the `printf` function available in all Go templates. This function is an alias to the Go function, [fmt.Printf](https://golang.org/pkg/fmt/). + +## What Variables are Available in this Context? + +You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`. + +``` +{{ printf "%#v" $.Site }} +``` + +This will print out the value of `.Permalink`: + + +``` +{{ printf "%#v" .Permalink }} +``` + + +This will print out a list of all the variables scoped to the current context +(`.`, aka ["the dot"][tempintro]). + + +``` +{{ printf "%#v" . }} +``` + + +When developing a [homepage][], what does one of the pages you're looping through look like? + +``` +{{ range .Pages }} + {{/* The context, ".", is now each one of the pages as it goes through the loop */}} + {{ printf "%#v" . }} +{{ end }} +``` + +## Why Am I Showing No Defined Variables? + +Check that you are passing variables in the `partial` function: + +``` +{{ partial "header" }} +``` + +This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][tempintro]. + +``` +{{ partial "header" . }} +``` + +The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see [Introduction to Hugo Templating][tempintro]. + +[homepage]: /templates/homepage/ +[tempintro]: /templates/introduction/ diff --git a/exampleSite/content/en/documentation/explanation/templates/views.md b/exampleSite/content/en/documentation/explanation/templates/views.md new file mode 100644 index 0000000..30c2948 --- /dev/null +++ b/exampleSite/content/en/documentation/explanation/templates/views.md @@ -0,0 +1,118 @@ +--- +title: Content View Templates +# linktitle: Content Views +description: Hugo can render alternative views of your content, which is especially useful in list and summary views. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [views] + +weight: 70 +sections_weight: 70 +draft: false +aliases: [] +toc: true +--- + +These alternative **content views** are especially useful in [list templates][lists]. + +The following are common use cases for content views: + +* You want content of every type to be shown on the homepage but only with limited [summary views][summaries]. +* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself. + +## Create a Content View + +To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view. + +``` + ▾ layouts/ + ▾ posts/ + li.html + single.html + summary.html + ▾ project/ + li.html + single.html + summary.html +``` + +Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order. + + +``` +▾ layouts/ + ▾ _default/ + li.html + single.html + summary.html +``` + +## Which Template Will be Rendered? + +The following is the [lookup order][lookup] for content views: + +1. `/layouts/<TYPE>/<VIEW>.html` +2. `/layouts/_default/<VIEW>.html` +3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html` +4. `/themes/<THEME>/layouts/_default/<VIEW>.html` + +## Example: Content View Inside a List + +The following example demonstrates how to use content views inside of your [list templates][lists]. + +### `list.html` + +In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows: + +{{< code file="layouts/_default/list.html" download="list.html" >}} +<main id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Pages }} + {{ .Render "summary"}} + {{ end }} + </div> +</main> +{{< /code >}} + +### `summary.html` + +Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.) + +{{< code file="layouts/_default/summary.html" download="summary.html" >}} +<article class="post"> + <header> + <h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2> + <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div> + </header> + {{ .Summary }} + <footer> + <a href='{{ .Permalink }}'><nobr>Read more →</nobr></a> + </footer> +</article> +{{< /code >}} + +### `li.html` + +Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`). + +{{< code file="layouts/_default/li.html" download="li.html" >}} +<li> + <a href="{{ .Permalink }}">{{ .Title }}</a> + <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> +</li> +{{< /code >}} + +[lists]: /templates/lists/ +[lookup]: /templates/lookup-order/ +[pagevars]: /variables/page/ +[render]: /functions/render/ +[single]: /templates/single-page-templates/ +[spf]: https://spf13.com +[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html +[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html +[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html +[summaries]: /content-management/summaries/ +[taxonomylists]: /templates/taxonomy-templates/ diff --git a/exampleSite/content/en/documentation/guides/_index.md b/exampleSite/content/en/documentation/guides/_index.md new file mode 100644 index 0000000..b5f2137 --- /dev/null +++ b/exampleSite/content/en/documentation/guides/_index.md @@ -0,0 +1,5 @@ +--- +title: "How-to Guides" +linkTitle: "Guides" +weight: 40 +--- diff --git a/exampleSite/content/en/documentation/guides/how-to-use-modbool.md b/exampleSite/content/en/documentation/guides/how-to-use-modbool.md new file mode 100644 index 0000000..6d16895 --- /dev/null +++ b/exampleSite/content/en/documentation/guides/how-to-use-modbool.md @@ -0,0 +1,4 @@ +--- +title: How to use the modBool function +keywords: ["math"] +---
\ No newline at end of file diff --git a/exampleSite/content/en/documentation/reference/_index.md b/exampleSite/content/en/documentation/reference/_index.md new file mode 100644 index 0000000..5011d0f --- /dev/null +++ b/exampleSite/content/en/documentation/reference/_index.md @@ -0,0 +1,5 @@ +--- +title: "Technical Reference" +linkTitle: "Reference" +weight: 10 +--- diff --git a/exampleSite/content/en/documentation/reference/functions/_index.md b/exampleSite/content/en/documentation/reference/functions/_index.md new file mode 100644 index 0000000..51173f6 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/_index.md @@ -0,0 +1,5 @@ +--- +title: "Function Namespaces" +linkTitle: "Functions" +weight: 10 +--- diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/cast/cast/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/cast/cast/index.md new file mode 100644 index 0000000..afc80c0 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/cast/cast/index.md @@ -0,0 +1,76 @@ + + + + + +--- +title: "cast" +linkTitle: "cast" +description: "Cast is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## cast.ToFloat {#cast_namespace_tofloat} + +\([any](/documentation/reference/gotypes/#any)\) → [float64](/documentation/reference/gotypes/#float64) +{.funcsig} +ToFloat converts the given value to a float. + + +{{< docs/func-aliases "cast.ToFloat" >}} +{{< docs/func-examples "cast.ToFloat" >}} + + + + + + + +## cast.ToInt {#cast_namespace_toint} + +\([any](/documentation/reference/gotypes/#any)\) → [int](/documentation/reference/gotypes/#int) +{.funcsig} +ToInt converts the given value to an int. + + +{{< docs/func-aliases "cast.ToInt" >}} +{{< docs/func-examples "cast.ToInt" >}} + + + + + + + +## cast.ToString {#cast_namespace_tostring} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +ToString converts the given value to a string. + + +{{< docs/func-aliases "cast.ToString" >}} +{{< docs/func-examples "cast.ToString" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/collections/collections/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/collections/collections/index.md new file mode 100644 index 0000000..030e1e0 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/collections/collections/index.md @@ -0,0 +1,526 @@ + + + + + +--- +title: "collections" +linkTitle: "collections" +description: "Collections is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## collections.After {#collections_namespace_after} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +After returns all the items after the first N in a rangeable list. + + +{{< docs/func-aliases "collections.After" >}} +{{< docs/func-examples "collections.After" >}} + + + + + + + +## collections.Append {#collections_namespace_append} + +\([](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Append appends the arguments up to the last one to the slice in the last argument. +This construct allows template constructs like this: + + +```go-html-template +{{ $pages = $pages | append $p2 $p1 }} + + +``` +Note that with 2 arguments where both are slices of the same type, +the first slice will be appended to the second: + + +```go-html-template +{{ $pages = $pages | append .Site.RegularPages }} + + +``` + +{{< docs/func-aliases "collections.Append" >}} +{{< docs/func-examples "collections.Append" >}} + + + + + + + +## collections.Apply {#collections_namespace_apply} + +\([any](/documentation/reference/gotypes/#any)[string](/documentation/reference/gotypes/#string)[](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Apply takes a map, array, or slice and returns a new slice with the function fname applied over it. + + +{{< docs/func-aliases "collections.Apply" >}} +{{< docs/func-examples "collections.Apply" >}} + + + + + + + +## collections.Complement {#collections_namespace_complement} + +\([](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Complement gives the elements in the last element of seqs that are not in +any of the others. +All elements of seqs must be slices or arrays of comparable types. + +The reasoning behind this rather clumsy API is so we can do this in the templates: + + +```go-html-template +{{ $c := .Pages | complement $last4 }} + + +``` + +{{< docs/func-aliases "collections.Complement" >}} +{{< docs/func-examples "collections.Complement" >}} + + + + + + + +## collections.Delimit {#collections_namespace_delimit} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +Delimit takes a given sequence and returns a delimited HTML string. +If last is passed to the function, it will be used as the final delimiter. + + +{{< docs/func-aliases "collections.Delimit" >}} +{{< docs/func-examples "collections.Delimit" >}} + + + + + + + +## collections.Dictionary {#collections_namespace_dictionary} + +\([](/documentation/reference/objects//)\) → [](/documentation/reference/objects//) +{.funcsig} +Dictionary creates a map[string]interface{} from the given parameters by +walking the parameters and treating them as key-value pairs. The number +of parameters must be even. +The keys can be string slices, which will create the needed nested structure. + + +{{< docs/func-aliases "collections.Dictionary" >}} +{{< docs/func-examples "collections.Dictionary" >}} + + + + + + + +## collections.EchoParam {#collections_namespace_echoparam} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +EchoParam returns a given value if it is set; otherwise, it returns an +empty string. + + +{{< docs/func-aliases "collections.EchoParam" >}} +{{< docs/func-examples "collections.EchoParam" >}} + + + + + + + +## collections.First {#collections_namespace_first} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +First returns the first N items in a rangeable list. + + +{{< docs/func-aliases "collections.First" >}} +{{< docs/func-examples "collections.First" >}} + + + + + + + +## collections.Group {#collections_namespace_group} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Group groups a set of elements by the given key. +This is currently only supported for [Pages](/documentation/reference/objects/resources/page/pages) . + + +{{< docs/func-aliases "collections.Group" >}} +{{< docs/func-examples "collections.Group" >}} + + + + + + + +## collections.In {#collections_namespace_in} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +In returns whether v is in the set l. l may be an array or slice. + + +{{< docs/func-aliases "collections.In" >}} +{{< docs/func-examples "collections.In" >}} + + + + + + + +## collections.Index {#collections_namespace_index} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Index returns the result of indexing its first argument by the following +arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each +indexed item must be a map, slice, or array. + +Copied from Go stdlib src/text/template/funcs.go. + +We deviate from the stdlib due to <a href="https://github.com/golang/go/issues/14751">https://github.com/golang/go/issues/14751</a>. + +TODO(moorereason): merge upstream changes. + + +{{< docs/func-aliases "collections.Index" >}} +{{< docs/func-examples "collections.Index" >}} + + + + + + + +## collections.Intersect {#collections_namespace_intersect} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Intersect returns the common elements in the given sets, l1 and l2. l1 and +l2 must be of the same type and may be either arrays or slices. + + +{{< docs/func-aliases "collections.Intersect" >}} +{{< docs/func-examples "collections.Intersect" >}} + + + + + + + +## collections.IsSet {#collections_namespace_isset} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +IsSet returns whether a given array, channel, slice, or map has a key +defined. + + +{{< docs/func-aliases "collections.IsSet" >}} +{{< docs/func-examples "collections.IsSet" >}} + + + + + + + +## collections.KeyVals {#collections_namespace_keyvals} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [KeyValues](/documentation/reference/objects/common/types/keyvalues) +{.funcsig} +KeyVals creates a key and values wrapper. + + +{{< docs/func-aliases "collections.KeyVals" >}} +{{< docs/func-examples "collections.KeyVals" >}} + + + + + + + +## collections.Last {#collections_namespace_last} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Last returns the last N items in a rangeable list. + + +{{< docs/func-aliases "collections.Last" >}} +{{< docs/func-examples "collections.Last" >}} + + + + + + + +## collections.Merge {#collections_namespace_merge} + +\([](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Merge creates a copy of the final parameter and merges the preceding +parameters into it in reverse order. +Currently only maps are supported. Key handling is case insensitive. + + +{{< docs/func-aliases "collections.Merge" >}} +{{< docs/func-examples "collections.Merge" >}} + + + + + + + +## collections.NewScratch {#collections_namespace_newscratch} + +\(\) → [](/documentation/reference/objects//) +{.funcsig} +NewScratch creates a new Scratch which can be used to store values in a +thread safe way. + + +{{< docs/func-aliases "collections.NewScratch" >}} +{{< docs/func-examples "collections.NewScratch" >}} + + + + + + + +## collections.Querify {#collections_namespace_querify} + +\([](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Querify encodes the given parameters in URL-encoded form ("bar=baz&foo=quux") sorted by key. + + +{{< docs/func-aliases "collections.Querify" >}} +{{< docs/func-examples "collections.Querify" >}} + + + + + + + +## collections.Reverse {#collections_namespace_reverse} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Reverse creates a copy of slice and reverses it. + + +{{< docs/func-aliases "collections.Reverse" >}} +{{< docs/func-examples "collections.Reverse" >}} + + + + + + + +## collections.Seq {#collections_namespace_seq} + +\([](/documentation/reference/objects//)\) → [](/documentation/reference/objects//) +{.funcsig} +Seq creates a sequence of integers. It's named and used as GNU's seq. + +Examples: + + +```go-html-template +3 => 1, 2, 3 + +1 2 4 => 1, 3 + +-3 => -1, -2, -3 + +1 4 => 1, 2, 3, 4 + +1 -2 => 1, 0, -1, -2 + + +``` + +{{< docs/func-aliases "collections.Seq" >}} +{{< docs/func-examples "collections.Seq" >}} + + + + + + + +## collections.Shuffle {#collections_namespace_shuffle} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Shuffle returns the given rangeable list in a randomised order. + + +{{< docs/func-aliases "collections.Shuffle" >}} +{{< docs/func-examples "collections.Shuffle" >}} + + + + + + + +## collections.Slice {#collections_namespace_slice} + +\([](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Slice returns a slice of all passed arguments. + + +{{< docs/func-aliases "collections.Slice" >}} +{{< docs/func-examples "collections.Slice" >}} + + + + + + + +## collections.Sort {#collections_namespace_sort} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Sort returns a sorted sequence. + + +{{< docs/func-aliases "collections.Sort" >}} +{{< docs/func-examples "collections.Sort" >}} + + + + + + + +## collections.SymDiff {#collections_namespace_symdiff} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +SymDiff returns the symmetric difference of s1 and s2. +Arguments must be either a slice or an array of comparable types. + + +{{< docs/func-aliases "collections.SymDiff" >}} +{{< docs/func-examples "collections.SymDiff" >}} + + + + + + + +## collections.Union {#collections_namespace_union} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Union returns the union of the given sets, l1 and l2. l1 and +l2 must be of the same type and may be either arrays or slices. +If l1 and l2 aren't of the same type then l1 will be returned. +If either l1 or l2 is nil then the non-nil list will be returned. + + +{{< docs/func-aliases "collections.Union" >}} +{{< docs/func-examples "collections.Union" >}} + + + + + + + +## collections.Uniq {#collections_namespace_uniq} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Uniq takes in a slice or array and returns a slice with subsequent +duplicate elements removed. + + +{{< docs/func-aliases "collections.Uniq" >}} +{{< docs/func-examples "collections.Uniq" >}} + + + + + + + +## collections.Where {#collections_namespace_where} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Where returns a filtered subset of a given data type. + + +{{< docs/func-aliases "collections.Where" >}} +{{< docs/func-examples "collections.Where" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/compare/compare/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/compare/compare/index.md new file mode 100644 index 0000000..999714d --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/compare/compare/index.md @@ -0,0 +1,162 @@ + + + + + +--- +title: "compare" +linkTitle: "compare" +description: "Compare is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## compare.Conditional {#compare_namespace_conditional} + +\([bool](/documentation/reference/gotypes/#bool)[any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Conditional can be used as a ternary operator. +It returns a if condition, else b. + + +{{< docs/func-aliases "compare.Conditional" >}} +{{< docs/func-examples "compare.Conditional" >}} + + + + + + + +## compare.Default {#compare_namespace_default} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Default checks whether a given value is set and returns a default value if it +is not. "Set" in this context means non-zero for numeric types and times; +non-zero length for strings, arrays, slices, and maps; +any boolean or struct value; or non-nil for any other types. + + +{{< docs/func-aliases "compare.Default" >}} +{{< docs/func-examples "compare.Default" >}} + + + + + + + +## compare.Eq {#compare_namespace_eq} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +Eq returns the boolean truth of arg1 == arg2 || arg1 == arg3 || arg1 == arg4. + + +{{< docs/func-aliases "compare.Eq" >}} +{{< docs/func-examples "compare.Eq" >}} + + + + + + + +## compare.Ge {#compare_namespace_ge} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +Ge returns the boolean truth of arg1 >= arg2 && arg1 >= arg3 && arg1 >= arg4. + + +{{< docs/func-aliases "compare.Ge" >}} +{{< docs/func-examples "compare.Ge" >}} + + + + + + + +## compare.Gt {#compare_namespace_gt} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +Gt returns the boolean truth of arg1 > arg2 && arg1 > arg3 && arg1 > arg4. + + +{{< docs/func-aliases "compare.Gt" >}} +{{< docs/func-examples "compare.Gt" >}} + + + + + + + +## compare.Le {#compare_namespace_le} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +Le returns the boolean truth of arg1 <= arg2 && arg1 <= arg3 && arg1 <= arg4. + + +{{< docs/func-aliases "compare.Le" >}} +{{< docs/func-examples "compare.Le" >}} + + + + + + + +## compare.Lt {#compare_namespace_lt} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +Lt returns the boolean truth of arg1 < arg2 && arg1 < arg3 && arg1 < arg4. + + +{{< docs/func-aliases "compare.Lt" >}} +{{< docs/func-examples "compare.Lt" >}} + + + + + + + + + +## compare.Ne {#compare_namespace_ne} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +Ne returns the boolean truth of arg1 != arg2 && arg1 != arg3 && arg1 != arg4. + + +{{< docs/func-aliases "compare.Ne" >}} +{{< docs/func-examples "compare.Ne" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/crypto/crypto/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/crypto/crypto/index.md new file mode 100644 index 0000000..10a2dda --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/crypto/crypto/index.md @@ -0,0 +1,108 @@ + + + + + +--- +title: "crypto" +linkTitle: "crypto" +description: "Crypto is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## crypto.FNV32a {#crypto_namespace_fnv32a} + +\([any](/documentation/reference/gotypes/#any)\) → [int](/documentation/reference/gotypes/#int) +{.funcsig} +FNV32a hashes using fnv32a algorithm + + +{{< docs/func-aliases "crypto.FNV32a" >}} +{{< docs/func-examples "crypto.FNV32a" >}} + + + + + + + +## crypto.HMAC {#crypto_namespace_hmac} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +HMAC returns a cryptographic hash that uses a key to sign a message. + + +{{< docs/func-aliases "crypto.HMAC" >}} +{{< docs/func-examples "crypto.HMAC" >}} + + + + + + + +## crypto.MD5 {#crypto_namespace_md5} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +MD5 hashes the given input and returns its MD5 checksum. + + +{{< docs/func-aliases "crypto.MD5" >}} +{{< docs/func-examples "crypto.MD5" >}} + + + + + + + +## crypto.SHA1 {#crypto_namespace_sha1} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +SHA1 hashes the given input and returns its SHA1 checksum. + + +{{< docs/func-aliases "crypto.SHA1" >}} +{{< docs/func-examples "crypto.SHA1" >}} + + + + + + + +## crypto.SHA256 {#crypto_namespace_sha256} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +SHA256 hashes the given input and returns its SHA256 checksum. + + +{{< docs/func-aliases "crypto.SHA256" >}} +{{< docs/func-examples "crypto.SHA256" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/data/data/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/data/data/index.md new file mode 100644 index 0000000..2c3cb29 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/data/data/index.md @@ -0,0 +1,66 @@ + + + + + +--- +title: "data" +linkTitle: "data" +description: "Data is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## data.GetCSV {#data_namespace_getcsv} + +\([string](/documentation/reference/gotypes/#string)[](/documentation/reference/objects//)\) → [](/documentation/reference/objects//) +{.funcsig} +GetCSV expects a data separator and one or n-parts of a URL to a resource which +can either be a local or a remote one. +The data separator can be a comma, semi-colon, pipe, etc, but only one character. +If you provide multiple parts for the URL they will be joined together to the final URL. +GetCSV returns nil or a slice slice to use in a short code. + + +{{< docs/func-aliases "data.GetCSV" >}} +{{< docs/func-examples "data.GetCSV" >}} + + + + + + + +## data.GetJSON {#data_namespace_getjson} + +\([](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +GetJSON expects one or n-parts of a URL to a resource which can either be a local or a remote one. +If you provide multiple parts they will be joined together to the final URL. +GetJSON returns nil or parsed JSON to use in a short code. + + +{{< docs/func-aliases "data.GetJSON" >}} +{{< docs/func-examples "data.GetJSON" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/debug/debug/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/debug/debug/index.md new file mode 100644 index 0000000..70d07d1 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/debug/debug/index.md @@ -0,0 +1,49 @@ + + + + + +--- +title: "debug" +linkTitle: "debug" +description: "Debug is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## debug.Dump {#debug_namespace_dump} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Dump returns a object dump of val as a string. +Note that not every value passed to Dump will print so nicely, but +we'll improve on that. We recommend using the "go" Chroma lexer to format the output +nicely. +Also note that the output from Dump may change from Hugo version to the next, +so don't depend on a specific output. + + +{{< docs/func-aliases "debug.Dump" >}} +{{< docs/func-examples "debug.Dump" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/diagrams/diagrams/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/diagrams/diagrams/index.md new file mode 100644 index 0000000..37d488f --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/diagrams/diagrams/index.md @@ -0,0 +1,18 @@ + + + + + +--- +title: "diagrams" +linkTitle: "diagrams" +description: "Diagrams is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/encoding/encoding/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/encoding/encoding/index.md new file mode 100644 index 0000000..b6f247d --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/encoding/encoding/index.md @@ -0,0 +1,80 @@ + + + + + +--- +title: "encoding" +linkTitle: "encoding" +description: "Encoding is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## encoding.Base64Decode {#encoding_namespace_base64decode} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Base64Decode returns the base64 decoding of the given content. + + +{{< docs/func-aliases "encoding.Base64Decode" >}} +{{< docs/func-examples "encoding.Base64Decode" >}} + + + + + + + +## encoding.Base64Encode {#encoding_namespace_base64encode} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Base64Encode returns the base64 encoding of the given content. + + +{{< docs/func-aliases "encoding.Base64Encode" >}} +{{< docs/func-examples "encoding.Base64Encode" >}} + + + + + + + +## encoding.Jsonify {#encoding_namespace_jsonify} + +\([](/documentation/reference/objects//)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +Jsonify encodes a given object to JSON. To pretty print the JSON, pass a map +or dictionary of options as the first argument. Supported options are +"prefix" and "indent". Each JSON element in the output will begin on a new +line beginning with prefix followed by one or more copies of indent according +to the indentation nesting. + + +{{< docs/func-aliases "encoding.Jsonify" >}} +{{< docs/func-examples "encoding.Jsonify" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/fmt/fmt/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/fmt/fmt/index.md new file mode 100644 index 0000000..be333e9 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/fmt/fmt/index.md @@ -0,0 +1,128 @@ + + + + + +--- +title: "fmt" +linkTitle: "fmt" +description: "Fmt is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## fmt.Errorf {#fmt_namespace_errorf} + +\([string](/documentation/reference/gotypes/#string)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Errorf formats according to a format specifier and logs an ERROR. +It returns an empty string. + + +{{< docs/func-aliases "fmt.Errorf" >}} +{{< docs/func-examples "fmt.Errorf" >}} + + + + + + + +## fmt.Erroridf {#fmt_namespace_erroridf} + +\([string](/documentation/reference/gotypes/#string)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Erroridf formats according to a format specifier and logs an ERROR and +an information text that the error with the given ID can be suppressed in config. +It returns an empty string. + + +{{< docs/func-aliases "fmt.Erroridf" >}} +{{< docs/func-examples "fmt.Erroridf" >}} + + + + + + + +## fmt.Print {#fmt_namespace_print} + +\([](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Print returns string representation of the passed arguments. + + +{{< docs/func-aliases "fmt.Print" >}} +{{< docs/func-examples "fmt.Print" >}} + + + + + + + +## fmt.Printf {#fmt_namespace_printf} + +\([string](/documentation/reference/gotypes/#string)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Printf returns a formatted string representation of the passed arguments. + + +{{< docs/func-aliases "fmt.Printf" >}} +{{< docs/func-examples "fmt.Printf" >}} + + + + + + + +## fmt.Println {#fmt_namespace_println} + +\([](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Println returns string representation of the passed arguments ending with a newline. + + +{{< docs/func-aliases "fmt.Println" >}} +{{< docs/func-examples "fmt.Println" >}} + + + + + + + +## fmt.Warnf {#fmt_namespace_warnf} + +\([string](/documentation/reference/gotypes/#string)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Warnf formats according to a format specifier and logs a WARNING. +It returns an empty string. + + +{{< docs/func-aliases "fmt.Warnf" >}} +{{< docs/func-examples "fmt.Warnf" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/hugo/hugo/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/hugo/hugo/index.md new file mode 100644 index 0000000..336e3d3 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/hugo/hugo/index.md @@ -0,0 +1,18 @@ + + + + + +--- +title: "hugo" +linkTitle: "hugo" +description: "Hugo is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/images/images/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/images/images/index.md new file mode 100644 index 0000000..ce0b90e --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/images/images/index.md @@ -0,0 +1,63 @@ + + + + + +--- +title: "images" +linkTitle: "images" +description: "Images is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + +tags: +- images + + + +--- + + + + + + + + + + + + + + + + + +## images.Config {#images_namespace_config} + +\([any](/documentation/reference/gotypes/#any)\) → [Config](/documentation/reference/objects/image/config) +{.funcsig} +Config returns the image.Config for the specified path relative to the +working directory. + + +{{< docs/func-aliases "images.Config" >}} +{{< docs/func-examples "images.Config" >}} + + + + + + + +## images.Filter {#images_namespace_filter} + +\([](/documentation/reference/objects//)\) → [ImageResource](/documentation/reference/objects/resources/images/imageresource) +{.funcsig} + +{{< docs/func-aliases "images.Filter" >}} +{{< docs/func-examples "images.Filter" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/inflect/inflect/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/inflect/inflect/index.md new file mode 100644 index 0000000..819fcf9 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/inflect/inflect/index.md @@ -0,0 +1,89 @@ + + + + + +--- +title: "inflect" +linkTitle: "inflect" +description: "Inflect is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## inflect.Humanize {#inflect_namespace_humanize} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Humanize returns the humanized form of a single parameter. + +If the parameter is either an integer or a string containing an integer +value, the behavior is to add the appropriate ordinal. + + +```go-html-template +Example: "my-first-post" -> "My first post" + +Example: "103" -> "103rd" + +Example: 52 -> "52nd" + + +``` + +{{< docs/func-aliases "inflect.Humanize" >}} +{{< docs/func-examples "inflect.Humanize" >}} + + + + + + + +## inflect.Pluralize {#inflect_namespace_pluralize} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Pluralize returns the plural form of a single word. + + +{{< docs/func-aliases "inflect.Pluralize" >}} +{{< docs/func-examples "inflect.Pluralize" >}} + + + + + + + +## inflect.Singularize {#inflect_namespace_singularize} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Singularize returns the singular form of a single word. + + +{{< docs/func-aliases "inflect.Singularize" >}} +{{< docs/func-examples "inflect.Singularize" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/internal/internal/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/internal/internal/index.md new file mode 100644 index 0000000..8ffc9fa --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/internal/internal/index.md @@ -0,0 +1,18 @@ + + + + + +--- +title: "internal" +linkTitle: "internal" +description: "Internal is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/js/js/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/js/js/index.md new file mode 100644 index 0000000..45f0540 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/js/js/index.md @@ -0,0 +1,44 @@ + + + + + +--- +title: "js" +linkTitle: "js" +description: "Js is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## js.Build {#js_namespace_build} + +\([](/documentation/reference/objects//)\) → [Resource](/documentation/reference/objects/resources/resource/resource) +{.funcsig} +Build processes the given Resource with ESBuild. + + +{{< docs/func-aliases "js.Build" >}} +{{< docs/func-examples "js.Build" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/lang/lang/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/lang/lang/index.md new file mode 100644 index 0000000..cc34d31 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/lang/lang/index.md @@ -0,0 +1,157 @@ + + + + + +--- +title: "lang" +linkTitle: "lang" +description: "Lang is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## lang.FormatAccounting {#lang_namespace_formataccounting} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +FormatAccounting returns the currency representation of number for the given currency and precision +for the current language in accounting notation. + +The return value is formatted with at least two decimal places. + + +{{< docs/func-aliases "lang.FormatAccounting" >}} +{{< docs/func-examples "lang.FormatAccounting" >}} + + + + + + + +## lang.FormatCurrency {#lang_namespace_formatcurrency} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +FormatCurrency returns the currency representation of number for the given currency and precision +for the current language. + +The return value is formatted with at least two decimal places. + + +{{< docs/func-aliases "lang.FormatCurrency" >}} +{{< docs/func-examples "lang.FormatCurrency" >}} + + + + + + + +## lang.FormatNumber {#lang_namespace_formatnumber} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +FormatNumber formats number with the given precision for the current language. + + +{{< docs/func-aliases "lang.FormatNumber" >}} +{{< docs/func-examples "lang.FormatNumber" >}} + + + + + + + +## lang.FormatNumberCustom {#lang_namespace_formatnumbercustom} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +FormatNumberCustom formats a number with the given precision using the +negative, decimal, and grouping options. The `options` +parameter is a string consisting of `<negative> <decimal> <grouping>`. The +default `options` value is `- . ,`. + +Note that numbers are rounded up at 5 or greater. +So, with precision set to 0, 1.5 becomes `2`, and 1.4 becomes `1`. + +For a simpler function that adapts to the current language, see FormatNumber. + + +{{< docs/func-aliases "lang.FormatNumberCustom" >}} +{{< docs/func-examples "lang.FormatNumberCustom" >}} + + + + + + + +## lang.FormatPercent {#lang_namespace_formatpercent} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +FormatPercent formats number with the given precision for the current language. +Note that the number is assumed to be a percentage. + + +{{< docs/func-aliases "lang.FormatPercent" >}} +{{< docs/func-examples "lang.FormatPercent" >}} + + + + + + + +## lang.Merge {#lang_namespace_merge} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Merge creates a union of pages from two languages. + + +{{< docs/func-aliases "lang.Merge" >}} +{{< docs/func-examples "lang.Merge" >}} + + + + + + + + + +## lang.Translate {#lang_namespace_translate} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Translate returns a translated string for id. + + +{{< docs/func-aliases "lang.Translate" >}} +{{< docs/func-examples "lang.Translate" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/math/math/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/math/math/index.md new file mode 100644 index 0000000..e58af44 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/math/math/index.md @@ -0,0 +1,272 @@ + + + + + +--- +title: "math" +linkTitle: "math" +description: "Math is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## math.Add {#math_namespace_add} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Add adds two numbers. + + +{{< docs/func-aliases "math.Add" >}} +{{< docs/func-examples "math.Add" >}} + + + + + + + +## math.Ceil {#math_namespace_ceil} + +\([any](/documentation/reference/gotypes/#any)\) → [float64](/documentation/reference/gotypes/#float64) +{.funcsig} +Ceil returns the least integer value greater than or equal to x. + + +{{< docs/func-aliases "math.Ceil" >}} +{{< docs/func-examples "math.Ceil" >}} + + + + + + + +## math.Counter {#math_namespace_counter} + +\(\) → [uint64](/documentation/reference/gotypes/#uint64) +{.funcsig} +Counter increments and returns a global counter. +This was originally added to be used in tests where now.UnixNano did not +have the needed precision (especially on Windows). +Note that given the parallel nature of Hugo, you cannot use this to get sequences of numbers, +and the counter will reset on new builds. + + +{{< docs/func-aliases "math.Counter" >}} +{{< docs/func-examples "math.Counter" >}} + + + + + + + +## math.Div {#math_namespace_div} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Div divides two numbers. + + +{{< docs/func-aliases "math.Div" >}} +{{< docs/func-examples "math.Div" >}} + + + + + + + +## math.Floor {#math_namespace_floor} + +\([any](/documentation/reference/gotypes/#any)\) → [float64](/documentation/reference/gotypes/#float64) +{.funcsig} +Floor returns the greatest integer value less than or equal to x. + + +{{< docs/func-aliases "math.Floor" >}} +{{< docs/func-examples "math.Floor" >}} + + + + + + + +## math.Log {#math_namespace_log} + +\([any](/documentation/reference/gotypes/#any)\) → [float64](/documentation/reference/gotypes/#float64) +{.funcsig} +Log returns the natural logarithm of a number. + + +{{< docs/func-aliases "math.Log" >}} +{{< docs/func-examples "math.Log" >}} + + + + + + + +## math.Max {#math_namespace_max} + +\([any](/documentation/reference/gotypes/#any)\) → [float64](/documentation/reference/gotypes/#float64) +{.funcsig} +Max returns the greater of two numbers. + + +{{< docs/func-aliases "math.Max" >}} +{{< docs/func-examples "math.Max" >}} + + + + + + + +## math.Min {#math_namespace_min} + +\([any](/documentation/reference/gotypes/#any)\) → [float64](/documentation/reference/gotypes/#float64) +{.funcsig} +Min returns the smaller of two numbers. + + +{{< docs/func-aliases "math.Min" >}} +{{< docs/func-examples "math.Min" >}} + + + + + + + +## math.Mod {#math_namespace_mod} + +\([any](/documentation/reference/gotypes/#any)\) → [int64](/documentation/reference/gotypes/#int64) +{.funcsig} +Mod returns a % b. + + +{{< docs/func-aliases "math.Mod" >}} +{{< docs/func-examples "math.Mod" >}} + + + + + + + +## math.ModBool {#math_namespace_modbool} + +\([any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +ModBool returns the boolean of a % b. If a % b == 0, return true. + + +{{< docs/func-aliases "math.ModBool" >}} +{{< docs/func-examples "math.ModBool" >}} + + + + + + + +## math.Mul {#math_namespace_mul} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Mul multiplies two numbers. + + +{{< docs/func-aliases "math.Mul" >}} +{{< docs/func-examples "math.Mul" >}} + + + + + + + +## math.Pow {#math_namespace_pow} + +\([any](/documentation/reference/gotypes/#any)\) → [float64](/documentation/reference/gotypes/#float64) +{.funcsig} +Pow returns a raised to the power of b. + + +{{< docs/func-aliases "math.Pow" >}} +{{< docs/func-examples "math.Pow" >}} + + + + + + + +## math.Round {#math_namespace_round} + +\([any](/documentation/reference/gotypes/#any)\) → [float64](/documentation/reference/gotypes/#float64) +{.funcsig} +Round returns the nearest integer, rounding half away from zero. + + +{{< docs/func-aliases "math.Round" >}} +{{< docs/func-examples "math.Round" >}} + + + + + + + +## math.Sqrt {#math_namespace_sqrt} + +\([any](/documentation/reference/gotypes/#any)\) → [float64](/documentation/reference/gotypes/#float64) +{.funcsig} +Sqrt returns the square root of a number. + + +{{< docs/func-aliases "math.Sqrt" >}} +{{< docs/func-examples "math.Sqrt" >}} + + + + + + + +## math.Sub {#math_namespace_sub} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Sub subtracts two numbers. + + +{{< docs/func-aliases "math.Sub" >}} +{{< docs/func-examples "math.Sub" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/openapi/openapi3/openapi/openapi3/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/openapi/openapi3/openapi/openapi3/index.md new file mode 100644 index 0000000..1b49d47 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/openapi/openapi3/openapi/openapi3/index.md @@ -0,0 +1,42 @@ + + + + + +--- +title: "openapi/openapi3" +linkTitle: "openapi/openapi3" +description: "Openapi/Openapi3 is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## openapi3.Unmarshal {#openapi3_namespace_unmarshal} + +\([UnmarshableResource](/documentation/reference/objects/resources/resource/unmarshableresource)\) → [](/documentation/reference/objects//) +{.funcsig} + +{{< docs/func-aliases "openapi3.Unmarshal" >}} +{{< docs/func-examples "openapi3.Unmarshal" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/os/os/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/os/os/index.md new file mode 100644 index 0000000..3aac5e9 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/os/os/index.md @@ -0,0 +1,111 @@ + + + + + +--- +title: "os" +linkTitle: "os" +description: "Os is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## os.FileExists {#os_namespace_fileexists} + +\([any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +FileExists checks whether a file exists under the given path. + + +{{< docs/func-aliases "os.FileExists" >}} +{{< docs/func-examples "os.FileExists" >}} + + + + + + + +## os.Getenv {#os_namespace_getenv} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Getenv retrieves the value of the environment variable named by the key. +It returns the value, which will be empty if the variable is not present. + + +{{< docs/func-aliases "os.Getenv" >}} +{{< docs/func-examples "os.Getenv" >}} + + + + + + + +## os.ReadDir {#os_namespace_readdir} + +\([any](/documentation/reference/gotypes/#any)\) → [](/documentation/reference/objects//) +{.funcsig} +ReadDir lists the directory contents relative to the configured WorkingDir. + + +{{< docs/func-aliases "os.ReadDir" >}} +{{< docs/func-examples "os.ReadDir" >}} + + + + + + + +## os.ReadFile {#os_namespace_readfile} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +ReadFile reads the file named by filename relative to the configured WorkingDir. +It returns the contents as a string. +There is an upper size limit set at 1 megabytes. + + +{{< docs/func-aliases "os.ReadFile" >}} +{{< docs/func-examples "os.ReadFile" >}} + + + + + + + +## os.Stat {#os_namespace_stat} + +\([any](/documentation/reference/gotypes/#any)\) → [FileInfo](/documentation/reference/objects/os/fileinfo) +{.funcsig} +Stat returns the os.FileInfo structure describing file. + + +{{< docs/func-aliases "os.Stat" >}} +{{< docs/func-examples "os.Stat" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/partials/partials/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/partials/partials/index.md new file mode 100644 index 0000000..9d8a704 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/partials/partials/index.md @@ -0,0 +1,65 @@ + + + + + +--- +title: "partials" +linkTitle: "partials" +description: "Partials is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## partials.Include {#partials_namespace_include} + +\([string](/documentation/reference/gotypes/#string)[](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Include executes the named partial. +If the partial contains a return statement, that value will be returned. +Else, the rendered output will be returned: +A string if the partial is a text/template, or template.HTML when html/template. +Note that ctx is provided by Hugo, not the end user. + + +{{< docs/func-aliases "partials.Include" >}} +{{< docs/func-examples "partials.Include" >}} + + + + + + + +## partials.IncludeCached {#partials_namespace_includecached} + +\([string](/documentation/reference/gotypes/#string)[any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +IncludeCached executes and caches partial templates. The cache is created with name+variants as the key. +Note that ctx is provided by Hugo, not the end user. + + +{{< docs/func-aliases "partials.IncludeCached" >}} +{{< docs/func-examples "partials.IncludeCached" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/path/path/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/path/path/index.md new file mode 100644 index 0000000..235da08 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/path/path/index.md @@ -0,0 +1,154 @@ + + + + + +--- +title: "path" +linkTitle: "path" +description: "Path is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## path.Base {#path_namespace_base} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Base returns the last element of path. +Trailing slashes are removed before extracting the last element. +If the path is empty, Base returns ".". +If the path consists entirely of slashes, Base returns "/". +The input path is passed into filepath.ToSlash converting any Windows slashes +to forward slashes. + + +{{< docs/func-aliases "path.Base" >}} +{{< docs/func-examples "path.Base" >}} + + + + + + + +## path.Clean {#path_namespace_clean} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Clean replaces the separators used with standard slashes and then +extraneous slashes are removed. + + +{{< docs/func-aliases "path.Clean" >}} +{{< docs/func-examples "path.Clean" >}} + + + + + + + +## path.Dir {#path_namespace_dir} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Dir returns all but the last element of path, typically the path's directory. +After dropping the final element using Split, the path is Cleaned and trailing +slashes are removed. +If the path is empty, Dir returns ".". +If the path consists entirely of slashes followed by non-slash bytes, Dir +returns a single slash. In any other case, the returned path does not end in a +slash. +The input path is passed into filepath.ToSlash converting any Windows slashes +to forward slashes. + + +{{< docs/func-aliases "path.Dir" >}} +{{< docs/func-examples "path.Dir" >}} + + + + + + + +## path.Ext {#path_namespace_ext} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Ext returns the file name extension used by path. +The extension is the suffix beginning at the final dot +in the final slash-separated element of path; +it is empty if there is no dot. +The input path is passed into filepath.ToSlash converting any Windows slashes +to forward slashes. + + +{{< docs/func-aliases "path.Ext" >}} +{{< docs/func-examples "path.Ext" >}} + + + + + + + +## path.Join {#path_namespace_join} + +\([](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Join joins any number of path elements into a single path, adding a +separating slash if necessary. All the input +path elements are passed into filepath.ToSlash converting any Windows slashes +to forward slashes. +The result is Cleaned; in particular, +all empty strings are ignored. + + +{{< docs/func-aliases "path.Join" >}} +{{< docs/func-examples "path.Join" >}} + + + + + + + +## path.Split {#path_namespace_split} + +\([any](/documentation/reference/gotypes/#any)\) → [DirFile](/documentation/reference/objects//dirfile) +{.funcsig} +Split splits path immediately following the final slash, +separating it into a directory and file name component. +If there is no slash in path, Split returns an empty dir and +file set to path. +The input path is passed into filepath.ToSlash converting any Windows slashes +to forward slashes. +The returned values have the property that path = dir+file. + + +{{< docs/func-aliases "path.Split" >}} +{{< docs/func-examples "path.Split" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/reflect/reflect/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/reflect/reflect/index.md new file mode 100644 index 0000000..798a3a1 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/reflect/reflect/index.md @@ -0,0 +1,60 @@ + + + + + +--- +title: "reflect" +linkTitle: "reflect" +description: "Reflect is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## reflect.IsMap {#reflect_namespace_ismap} + +\([any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +IsMap reports whether v is a map. + + +{{< docs/func-aliases "reflect.IsMap" >}} +{{< docs/func-examples "reflect.IsMap" >}} + + + + + + + +## reflect.IsSlice {#reflect_namespace_isslice} + +\([any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +IsSlice reports whether v is a slice. + + +{{< docs/func-aliases "reflect.IsSlice" >}} +{{< docs/func-examples "reflect.IsSlice" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/safe/safe/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/safe/safe/index.md new file mode 100644 index 0000000..521d90d --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/safe/safe/index.md @@ -0,0 +1,140 @@ + + + + + +--- +title: "safe" +linkTitle: "safe" +description: "Safe is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## safe.CSS {#safe_namespace_css} + +\([any](/documentation/reference/gotypes/#any)\) → [CSS](/documentation/reference/objects/html/template/css) +{.funcsig} +CSS returns a given string as html/template CSS content. + + +{{< docs/func-aliases "safe.CSS" >}} +{{< docs/func-examples "safe.CSS" >}} + + + + + + + +## safe.HTML {#safe_namespace_html} + +\([any](/documentation/reference/gotypes/#any)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +HTML returns a given string as html/template HTML content. + + +{{< docs/func-aliases "safe.HTML" >}} +{{< docs/func-examples "safe.HTML" >}} + + + + + + + +## safe.HTMLAttr {#safe_namespace_htmlattr} + +\([any](/documentation/reference/gotypes/#any)\) → [HTMLAttr](/documentation/reference/objects/html/template/htmlattr) +{.funcsig} +HTMLAttr returns a given string as html/template HTMLAttr content. + + +{{< docs/func-aliases "safe.HTMLAttr" >}} +{{< docs/func-examples "safe.HTMLAttr" >}} + + + + + + + +## safe.JS {#safe_namespace_js} + +\([any](/documentation/reference/gotypes/#any)\) → [JS](/documentation/reference/objects/html/template/js) +{.funcsig} +JS returns the given string as a html/template JS content. + + +{{< docs/func-aliases "safe.JS" >}} +{{< docs/func-examples "safe.JS" >}} + + + + + + + +## safe.JSStr {#safe_namespace_jsstr} + +\([any](/documentation/reference/gotypes/#any)\) → [JSStr](/documentation/reference/objects/html/template/jsstr) +{.funcsig} +JSStr returns the given string as a html/template JSStr content. + + +{{< docs/func-aliases "safe.JSStr" >}} +{{< docs/func-examples "safe.JSStr" >}} + + + + + + + +## safe.SanitizeURL {#safe_namespace_sanitizeurl} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +SanitizeURL returns a given string as html/template URL content. + + +{{< docs/func-aliases "safe.SanitizeURL" >}} +{{< docs/func-examples "safe.SanitizeURL" >}} + + + + + + + +## safe.URL {#safe_namespace_url} + +\([any](/documentation/reference/gotypes/#any)\) → [URL](/documentation/reference/objects/html/template/url) +{.funcsig} +URL returns a given string as html/template URL content. + + +{{< docs/func-aliases "safe.URL" >}} +{{< docs/func-examples "safe.URL" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/site/site/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/site/site/index.md new file mode 100644 index 0000000..f1db0b9 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/site/site/index.md @@ -0,0 +1,18 @@ + + + + + +--- +title: "site" +linkTitle: "site" +description: "Site is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/strings/strings/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/strings/strings/index.md new file mode 100644 index 0000000..5b188ea --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/strings/strings/index.md @@ -0,0 +1,471 @@ + + + + + +--- +title: "strings" +linkTitle: "strings" +description: "Strings is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## strings.Chomp {#strings_namespace_chomp} + +\([any](/documentation/reference/gotypes/#any)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Chomp returns a copy of s with all trailing newline characters removed. + + +{{< docs/func-aliases "strings.Chomp" >}} +{{< docs/func-examples "strings.Chomp" >}} + + + + + + + +## strings.Contains {#strings_namespace_contains} + +\([any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +Contains reports whether substr is in s. + + +{{< docs/func-aliases "strings.Contains" >}} +{{< docs/func-examples "strings.Contains" >}} + + + + + + + +## strings.ContainsAny {#strings_namespace_containsany} + +\([any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +ContainsAny reports whether any Unicode code points in chars are within s. + + +{{< docs/func-aliases "strings.ContainsAny" >}} +{{< docs/func-examples "strings.ContainsAny" >}} + + + + + + + +## strings.Count {#strings_namespace_count} + +\([any](/documentation/reference/gotypes/#any)\) → [int](/documentation/reference/gotypes/#int) +{.funcsig} +Count counts the number of non-overlapping instances of substr in s. +If substr is an empty string, Count returns 1 + the number of Unicode code points in s. + + +{{< docs/func-aliases "strings.Count" >}} +{{< docs/func-examples "strings.Count" >}} + + + + + + + +## strings.CountRunes {#strings_namespace_countrunes} + +\([any](/documentation/reference/gotypes/#any)\) → [int](/documentation/reference/gotypes/#int) +{.funcsig} +CountRunes returns the number of runes in s, excluding whitespace. + + +{{< docs/func-aliases "strings.CountRunes" >}} +{{< docs/func-examples "strings.CountRunes" >}} + + + + + + + +## strings.CountWords {#strings_namespace_countwords} + +\([any](/documentation/reference/gotypes/#any)\) → [int](/documentation/reference/gotypes/#int) +{.funcsig} +CountWords returns the approximate word count in s. + + +{{< docs/func-aliases "strings.CountWords" >}} +{{< docs/func-examples "strings.CountWords" >}} + + + + + + + +## strings.FindRE {#strings_namespace_findre} + +\([string](/documentation/reference/gotypes/#string)[any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [](/documentation/reference/objects//) +{.funcsig} +FindRE returns a list of strings that match the regular expression. By default all matches +will be included. The number of matches can be limited with an optional third parameter. + + +{{< docs/func-aliases "strings.FindRE" >}} +{{< docs/func-examples "strings.FindRE" >}} + + + + + + + +## strings.FirstUpper {#strings_namespace_firstupper} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +FirstUpper returns a string with the first character as upper case. + + +{{< docs/func-aliases "strings.FirstUpper" >}} +{{< docs/func-examples "strings.FirstUpper" >}} + + + + + + + +## strings.HasPrefix {#strings_namespace_hasprefix} + +\([any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +HasPrefix tests whether the input s begins with prefix. + + +{{< docs/func-aliases "strings.HasPrefix" >}} +{{< docs/func-examples "strings.HasPrefix" >}} + + + + + + + +## strings.HasSuffix {#strings_namespace_hassuffix} + +\([any](/documentation/reference/gotypes/#any)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +HasSuffix tests whether the input s begins with suffix. + + +{{< docs/func-aliases "strings.HasSuffix" >}} +{{< docs/func-examples "strings.HasSuffix" >}} + + + + + + + +## strings.Repeat {#strings_namespace_repeat} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Repeat returns a new string consisting of count copies of the string s. + + +{{< docs/func-aliases "strings.Repeat" >}} +{{< docs/func-examples "strings.Repeat" >}} + + + + + + + +## strings.Replace {#strings_namespace_replace} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Replace returns a copy of the string s with all occurrences of old replaced +with new. The number of replacements can be limited with an optional fourth +parameter. + + +{{< docs/func-aliases "strings.Replace" >}} +{{< docs/func-examples "strings.Replace" >}} + + + + + + + +## strings.ReplaceRE {#strings_namespace_replacere} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +ReplaceRE returns a copy of s, replacing all matches of the regular +expression pattern with the replacement text repl. The number of replacements +can be limited with an optional fourth parameter. + + +{{< docs/func-aliases "strings.ReplaceRE" >}} +{{< docs/func-examples "strings.ReplaceRE" >}} + + + + + + + +## strings.RuneCount {#strings_namespace_runecount} + +\([any](/documentation/reference/gotypes/#any)\) → [int](/documentation/reference/gotypes/#int) +{.funcsig} +RuneCount returns the number of runes in s. + + +{{< docs/func-aliases "strings.RuneCount" >}} +{{< docs/func-examples "strings.RuneCount" >}} + + + + + + + +## strings.SliceString {#strings_namespace_slicestring} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +SliceString slices a string by specifying a half-open range with +two indices, start and end. 1 and 4 creates a slice including elements 1 through 3. +The end index can be omitted, it defaults to the string's length. + + +{{< docs/func-aliases "strings.SliceString" >}} +{{< docs/func-examples "strings.SliceString" >}} + + + + + + + +## strings.Split {#strings_namespace_split} + +\([any](/documentation/reference/gotypes/#any)[string](/documentation/reference/gotypes/#string)\) → [](/documentation/reference/objects//) +{.funcsig} +Split slices an input string into all substrings separated by delimiter. + + +{{< docs/func-aliases "strings.Split" >}} +{{< docs/func-examples "strings.Split" >}} + + + + + + + +## strings.Substr {#strings_namespace_substr} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Substr extracts parts of a string, beginning at the character at the specified +position, and returns the specified number of characters. + +It normally takes two parameters: start and length. +It can also take one parameter: start, i.e. length is omitted, in which case +the substring starting from start until the end of the string will be returned. + +To extract characters from the end of the string, use a negative start number. + +In addition, borrowing from the extended behavior described at <a href="http://php.net/substr">http://php.net/substr</a>, +if length is given and is negative, then that many characters will be omitted from +the end of string. + + +{{< docs/func-aliases "strings.Substr" >}} +{{< docs/func-examples "strings.Substr" >}} + + + + + + + +## strings.Title {#strings_namespace_title} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Title returns a copy of the input s with all Unicode letters that begin words +mapped to their title case. + + +{{< docs/func-aliases "strings.Title" >}} +{{< docs/func-examples "strings.Title" >}} + + + + + + + +## strings.ToLower {#strings_namespace_tolower} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +ToLower returns a copy of the input s with all Unicode letters mapped to their +lower case. + + +{{< docs/func-aliases "strings.ToLower" >}} +{{< docs/func-examples "strings.ToLower" >}} + + + + + + + +## strings.ToUpper {#strings_namespace_toupper} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +ToUpper returns a copy of the input s with all Unicode letters mapped to their +upper case. + + +{{< docs/func-aliases "strings.ToUpper" >}} +{{< docs/func-examples "strings.ToUpper" >}} + + + + + + + +## strings.Trim {#strings_namespace_trim} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Trim returns a string with all leading and trailing characters defined +contained in cutset removed. + + +{{< docs/func-aliases "strings.Trim" >}} +{{< docs/func-examples "strings.Trim" >}} + + + + + + + +## strings.TrimLeft {#strings_namespace_trimleft} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +TrimLeft returns a slice of the string s with all leading characters +contained in cutset removed. + + +{{< docs/func-aliases "strings.TrimLeft" >}} +{{< docs/func-examples "strings.TrimLeft" >}} + + + + + + + +## strings.TrimPrefix {#strings_namespace_trimprefix} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +TrimPrefix returns s without the provided leading prefix string. If s doesn't +start with prefix, s is returned unchanged. + + +{{< docs/func-aliases "strings.TrimPrefix" >}} +{{< docs/func-examples "strings.TrimPrefix" >}} + + + + + + + +## strings.TrimRight {#strings_namespace_trimright} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +TrimRight returns a slice of the string s with all trailing characters +contained in cutset removed. + + +{{< docs/func-aliases "strings.TrimRight" >}} +{{< docs/func-examples "strings.TrimRight" >}} + + + + + + + +## strings.TrimSuffix {#strings_namespace_trimsuffix} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +TrimSuffix returns s without the provided trailing suffix string. If s +doesn't end with suffix, s is returned unchanged. + + +{{< docs/func-aliases "strings.TrimSuffix" >}} +{{< docs/func-examples "strings.TrimSuffix" >}} + + + + + + + +## strings.Truncate {#strings_namespace_truncate} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +Truncate truncates a given string to the specified length. + + +{{< docs/func-aliases "strings.Truncate" >}} +{{< docs/func-examples "strings.Truncate" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/templates/templates/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/templates/templates/index.md new file mode 100644 index 0000000..6f21ed8 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/templates/templates/index.md @@ -0,0 +1,46 @@ + + + + + +--- +title: "templates" +linkTitle: "templates" +description: "Templates is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## templates.Exists {#templates_namespace_exists} + +\([string](/documentation/reference/gotypes/#string)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +Exists returns whether the template with the given name exists. +Note that this is the Unix-styled relative path including filename suffix, +e.g. partials/header.html + + +{{< docs/func-aliases "templates.Exists" >}} +{{< docs/func-examples "templates.Exists" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/time/time/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/time/time/index.md new file mode 100644 index 0000000..2774966 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/time/time/index.md @@ -0,0 +1,117 @@ + + + + + +--- +title: "time" +linkTitle: "time" +description: "Time is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## time.AsTime {#time_namespace_astime} + +\([any](/documentation/reference/gotypes/#any)[](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +AsTime converts the textual representation of the datetime string into +a time.Time interface. + + +{{< docs/func-aliases "time.AsTime" >}} +{{< docs/func-examples "time.AsTime" >}} + + + + + + + +## time.Duration {#time_namespace_duration} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)\) → [Duration](/documentation/reference/objects/time/duration) +{.funcsig} +Duration converts the given number to a time.Duration. +Unit is one of nanosecond/ns, microsecond/us/µs, millisecond/ms, second/s, minute/m or hour/h. + + +{{< docs/func-aliases "time.Duration" >}} +{{< docs/func-examples "time.Duration" >}} + + + + + + + +## time.Format {#time_namespace_format} + +\([string](/documentation/reference/gotypes/#string)[any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Format converts the textual representation of the datetime string into +the other form or returns it of the time.Time value. These are formatted +with the layout string + + +{{< docs/func-aliases "time.Format" >}} +{{< docs/func-examples "time.Format" >}} + + + + + + + +## time.Now {#time_namespace_now} + +\(\) → [time.Time](/documentation/reference/gotypes/#timetime) +{.funcsig} +Now returns the current local time. + + +{{< docs/func-aliases "time.Now" >}} +{{< docs/func-examples "time.Now" >}} + + + + + + + +## time.ParseDuration {#time_namespace_parseduration} + +\([any](/documentation/reference/gotypes/#any)\) → [Duration](/documentation/reference/objects/time/duration) +{.funcsig} +ParseDuration parses a duration string. +A duration string is a possibly signed sequence of +decimal numbers, each with optional fraction and a unit suffix, +such as "300ms", "-1.5h" or "2h45m". +Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". +See <a href="https://golang.org/pkg/time/#ParseDuration">https://golang.org/pkg/time/#ParseDuration</a> + + +{{< docs/func-aliases "time.ParseDuration" >}} +{{< docs/func-examples "time.ParseDuration" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/transform/transform/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/transform/transform/index.md new file mode 100644 index 0000000..6588ce0 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/transform/transform/index.md @@ -0,0 +1,213 @@ + + + + + +--- +title: "transform" +linkTitle: "transform" +description: "Transform is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## transform.CanHighlight {#transform_namespace_canhighlight} + +\([string](/documentation/reference/gotypes/#string)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +CanHighlight returns whether the given language is supported by the Chroma highlighter. + + +{{< docs/func-aliases "transform.CanHighlight" >}} +{{< docs/func-examples "transform.CanHighlight" >}} + + + + + + + +## transform.Emojify {#transform_namespace_emojify} + +\([any](/documentation/reference/gotypes/#any)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +Emojify returns a copy of s with all emoji codes replaced with actual emojis. + +See <a href="http://www.emoji-cheat-sheet.com/">http://www.emoji-cheat-sheet.com/</a> + + +{{< docs/func-aliases "transform.Emojify" >}} +{{< docs/func-examples "transform.Emojify" >}} + + + + + + + +## transform.HTMLEscape {#transform_namespace_htmlescape} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +HTMLEscape returns a copy of s with reserved HTML characters escaped. + + +{{< docs/func-aliases "transform.HTMLEscape" >}} +{{< docs/func-examples "transform.HTMLEscape" >}} + + + + + + + +## transform.HTMLUnescape {#transform_namespace_htmlunescape} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +HTMLUnescape returns a copy of with HTML escape requences converted to plain +text. + + +{{< docs/func-aliases "transform.HTMLUnescape" >}} +{{< docs/func-examples "transform.HTMLUnescape" >}} + + + + + + + +## transform.Highlight {#transform_namespace_highlight} + +\([any](/documentation/reference/gotypes/#any)[string](/documentation/reference/gotypes/#string)[](/documentation/reference/objects//)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +Highlight returns a copy of s as an HTML string with syntax +highlighting applied. + + +{{< docs/func-aliases "transform.Highlight" >}} +{{< docs/func-examples "transform.Highlight" >}} + + + + + + + +## transform.HighlightCodeBlock {#transform_namespace_highlightcodeblock} + +\([CodeblockContext](/documentation/reference/objects/markup/converter/hooks/codeblockcontext)[](/documentation/reference/objects//)\) → [HightlightResult](/documentation/reference/objects/markup/highlight/hightlightresult) +{.funcsig} +HighlightCodeBlock highlights a code block on the form received in the codeblock render hooks. + + +{{< docs/func-aliases "transform.HighlightCodeBlock" >}} +{{< docs/func-examples "transform.HighlightCodeBlock" >}} + + + + + + + +## transform.Markdownify {#transform_namespace_markdownify} + +\([any](/documentation/reference/gotypes/#any)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +Markdownify renders a given input from Markdown to HTML. + + +{{< docs/func-aliases "transform.Markdownify" >}} +{{< docs/func-examples "transform.Markdownify" >}} + + + + + + + +## transform.Plainify {#transform_namespace_plainify} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Plainify returns a copy of s with all HTML tags removed. + + +{{< docs/func-aliases "transform.Plainify" >}} +{{< docs/func-examples "transform.Plainify" >}} + + + + + + + +## transform.Remarshal {#transform_namespace_remarshal} + +\([string](/documentation/reference/gotypes/#string)[any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Remarshal is used in the Hugo documentation to convert configuration +examples from YAML to JSON, TOML (and possibly the other way around). +The is primarily a helper for the Hugo docs site. +It is not a general purpose YAML to TOML converter etc., and may +change without notice if it serves a purpose in the docs. +Format is one of json, yaml or toml. + + +{{< docs/func-aliases "transform.Remarshal" >}} +{{< docs/func-examples "transform.Remarshal" >}} + + + + + + + +## transform.Reset {#transform_namespace_reset} + +\(\) → +{.funcsig} + +{{< docs/func-aliases "transform.Reset" >}} +{{< docs/func-examples "transform.Reset" >}} + + + + + + + +## transform.Unmarshal {#transform_namespace_unmarshal} + +\([](/documentation/reference/objects//)\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Unmarshal unmarshals the data given, which can be either a string, json.RawMessage +or a Resource. Supported formats are JSON, TOML, YAML, and CSV. +You can optionally provide an options map as the first argument. + + +{{< docs/func-aliases "transform.Unmarshal" >}} +{{< docs/func-examples "transform.Unmarshal" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/functions/tpl/urls/urls/index.md b/exampleSite/content/en/documentation/reference/functions/tpl/urls/urls/index.md new file mode 100644 index 0000000..f93ca87 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/functions/tpl/urls/urls/index.md @@ -0,0 +1,177 @@ + + + + + +--- +title: "urls" +linkTitle: "urls" +description: "Urls is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + + + + + + +## urls.AbsLangURL {#urls_namespace_abslangurl} + +\([any](/documentation/reference/gotypes/#any)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +AbsLangURL takes a given string and converts it to an absolute URL according +to a page's position in the project directory structure and the current +language. + + +{{< docs/func-aliases "urls.AbsLangURL" >}} +{{< docs/func-examples "urls.AbsLangURL" >}} + + + + + + + +## urls.AbsURL {#urls_namespace_absurl} + +\([any](/documentation/reference/gotypes/#any)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +AbsURL takes a given string and converts it to an absolute URL. + + +{{< docs/func-aliases "urls.AbsURL" >}} +{{< docs/func-examples "urls.AbsURL" >}} + + + + + + + +## urls.Anchorize {#urls_namespace_anchorize} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Anchorize creates sanitized anchor names that are compatible with Blackfriday. + + +{{< docs/func-aliases "urls.Anchorize" >}} +{{< docs/func-examples "urls.Anchorize" >}} + + + + + + + +## urls.Parse {#urls_namespace_parse} + +\([any](/documentation/reference/gotypes/#any)\) → [](/documentation/reference/objects//) +{.funcsig} +Parse parses rawurl into a URL structure. The rawurl may be relative or +absolute. + + +{{< docs/func-aliases "urls.Parse" >}} +{{< docs/func-examples "urls.Parse" >}} + + + + + + + +## urls.Ref {#urls_namespace_ref} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +Ref returns the absolute URL path to a given content item. + + +{{< docs/func-aliases "urls.Ref" >}} +{{< docs/func-examples "urls.Ref" >}} + + + + + + + +## urls.RelLangURL {#urls_namespace_rellangurl} + +\([any](/documentation/reference/gotypes/#any)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +RelLangURL takes a given string and prepends the relative path according to a +page's position in the project directory structure and the current language. + + +{{< docs/func-aliases "urls.RelLangURL" >}} +{{< docs/func-examples "urls.RelLangURL" >}} + + + + + + + +## urls.RelRef {#urls_namespace_relref} + +\([any](/documentation/reference/gotypes/#any)[any](/documentation/reference/gotypes/#any)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +RelRef returns the relative URL path to a given content item. + + +{{< docs/func-aliases "urls.RelRef" >}} +{{< docs/func-examples "urls.RelRef" >}} + + + + + + + +## urls.RelURL {#urls_namespace_relurl} + +\([any](/documentation/reference/gotypes/#any)\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +RelURL takes a given string and prepends the relative path according to a +page's position in the project directory structure. + + +{{< docs/func-aliases "urls.RelURL" >}} +{{< docs/func-examples "urls.RelURL" >}} + + + + + + + +## urls.URLize {#urls_namespace_urlize} + +\([any](/documentation/reference/gotypes/#any)\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +URLize returns the given argument formatted as URL. + + +{{< docs/func-aliases "urls.URLize" >}} +{{< docs/func-examples "urls.URLize" >}} + + + + + diff --git a/exampleSite/content/en/documentation/reference/gotypes/index.md b/exampleSite/content/en/documentation/reference/gotypes/index.md new file mode 100644 index 0000000..c873263 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/gotypes/index.md @@ -0,0 +1,37 @@ +--- +title: "Go Types" +slug: "gotypes" +weight: 1000 +--- + +## any + +Consectetur dolore ut fugiat reprehenderit consequat eiusmod adipisicing consectetur irure. Quis commodo amet ipsum cillum et nostrud pariatur exercitation mollit culpa. Pariatur nisi irure culpa non sit reprehenderit enim. + +Adipisicing minim culpa qui magna amet Lorem fugiat sit proident mollit. Magna sint cupidatat ut sint sit commodo irure. Deserunt consectetur cupidatat aliquip magna non aliquip nulla anim. Quis excepteur occaecat ipsum ad consectetur eiusmod excepteur ipsum. Ullamco sunt velit enim dolore voluptate. + + +## bool + +Eu consequat irure labore sit. Occaecat quis tempor veniam tempor quis ullamco ipsum nulla do proident. Velit officia aute irure veniam aliqua labore ullamco. Consequat ad ullamco labore sit fugiat laborum ad ex exercitation sit commodo reprehenderit labore. Nostrud officia ut aliquip aliquip culpa do. + +Irure officia proident commodo consequat ipsum quis duis duis irure. Cillum amet culpa ad veniam pariatur consequat. Elit voluptate laborum quis sunt consequat. + + +## string + +Irure sit minim sit nostrud mollit sit culpa do Lorem nulla. Anim elit enim labore cillum irure nostrud eu quis ad sit. Dolor id nostrud excepteur dolor magna labore dolore id. Occaecat id consequat id ea esse. Pariatur duis est proident ullamco eu non elit. + +Et excepteur enim cillum eu veniam veniam consectetur voluptate officia est. Enim mollit esse proident in. Duis anim sunt fugiat velit non non esse culpa do dolore nulla. Aute occaecat ullamco et sit est adipisicing sunt sunt minim esse. Est id pariatur ea nisi. + +## template.HTML + +Sunt Lorem esse officia culpa culpa voluptate pariatur minim ullamco tempor. Excepteur do proident amet et consequat amet laborum. Amet eiusmod enim aliquip irure exercitation tempor esse aliqua irure non dolore nostrud. Eu laboris magna dolore et cupidatat amet incididunt eiusmod. + +Nisi pariatur occaecat amet laboris consequat excepteur. Voluptate anim enim eu est ullamco esse minim ut pariatur. Elit ad fugiat proident sit magna do eiusmod sint ut sunt magna. Ipsum eiusmod qui proident eu sint excepteur sit culpa minim nulla id. + +## time.Time + +Commodo exercitation et exercitation ipsum sunt ea mollit nulla consequat quis labore exercitation aute aute. Non voluptate officia occaecat sunt magna velit sunt dolore voluptate fugiat reprehenderit tempor anim dolor. Dolore non culpa consequat est in quis dolor minim fugiat dolore commodo occaecat dolore enim. Quis amet do in Lorem. + +Officia cillum culpa dolor exercitation duis. Voluptate amet aute dolore nulla. Ipsum cupidatat nostrud dolore sit commodo. Qui ullamco amet in officia excepteur ex do enim consectetur esse quis ea duis ullamco. Eiusmod ipsum exercitation est voluptate quis tempor nulla eiusmod velit. diff --git a/exampleSite/content/en/documentation/reference/objects/_index.md b/exampleSite/content/en/documentation/reference/objects/_index.md new file mode 100644 index 0000000..77d0ee1 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/objects/_index.md @@ -0,0 +1,3 @@ +--- +title: Objects +--- diff --git a/exampleSite/content/en/documentation/reference/objects/hugo/index.md b/exampleSite/content/en/documentation/reference/objects/hugo/index.md new file mode 100644 index 0000000..155d303 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/objects/hugo/index.md @@ -0,0 +1,118 @@ + + + +--- +title: "Hugo" +linkTitle: "Hugo" +description: "Hugo is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + +keywords: +- hugo + +weight: 10 +--- + + + + + + + + + + +CommitHash +: {#hugo_info_commithash} + + + + + + +BuildDate +: {#hugo_info_builddate} + + + + + + +Environment +: The build environment. +Defaults are "production" (hugo) and "development" (hugo server). +This can also be set by the user. +It can be any string, but it will be all lower case. + +{#hugo_info_environment} + + + + + + + + + + + +## Deps {#hugo_info_deps} + +\(\) → [](/documentation/reference/objects//) +{.funcsig} +Deps gets a list of dependencies for this Hugo build. + + + + + + + + +## Generator {#hugo_info_generator} + +\(\) → [HTML](/documentation/reference/objects/html/template/html) +{.funcsig} +Generator a Hugo meta generator HTML tag. + + + + + + + + +## IsExtended {#hugo_info_isextended} + +\(\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} + + + + + + + +## IsProduction {#hugo_info_isproduction} + +\(\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} + + + + + + + +## Version {#hugo_info_version} + +\(\) → [VersionString](/documentation/reference/objects//versionstring) +{.funcsig} +Version returns the current version as a comparable version string. + + + + + + diff --git a/exampleSite/content/en/documentation/reference/objects/hugoinfo/index.md b/exampleSite/content/en/documentation/reference/objects/hugoinfo/index.md new file mode 100644 index 0000000..6a81ce6 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/objects/hugoinfo/index.md @@ -0,0 +1,118 @@ + + + +--- +title: "HugoInfo" +linkTitle: "HugoInfo" +description: "HugoInfo is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + +keywords: +- hugo + +weight: 10 +--- + + + + + + + + + + +CommitHash +: {#hugo_info_commithash} + + + + + + +BuildDate +: {#hugo_info_builddate} + + + + + + +Environment +: The build environment. +Defaults are "production" (hugo) and "development" (hugo server). +This can also be set by the user. +It can be any string, but it will be all lower case. + +{#hugo_info_environment} + + + + + + + + + + + +## Deps {#hugo_info_deps} + +\(\) → [.](/documentation/reference/objects//) +{.funcsig} +Deps gets a list of dependencies for this Hugo build. + + + + + + + + +## Generator {#hugo_info_generator} + +\(\) → [template.HTML](/documentation/reference/gotypes/#templatehtml) +{.funcsig} +Generator a Hugo meta generator HTML tag. + + + + + + + + +## IsExtended {#hugo_info_isextended} + +\(\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} + + + + + + + +## IsProduction {#hugo_info_isproduction} + +\(\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} + + + + + + + +## Version {#hugo_info_version} + +\(\) → [.VersionString](/documentation/reference/objects//versionstring) +{.funcsig} +Version returns the current version as a comparable version string. + + + + + + diff --git a/exampleSite/content/en/documentation/reference/objects/langs/language/index.md b/exampleSite/content/en/documentation/reference/objects/langs/language/index.md new file mode 100644 index 0000000..8b3cb62 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/objects/langs/language/index.md @@ -0,0 +1,104 @@ + + + +--- +title: "Language" +linkTitle: "Language" +description: "Language is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + +keywords: +- language +- i18n + + +--- + + + + + + + + + + +Lang +: {#langs_language_lang} + + + + + + +LanguageName +: {#langs_language_languagename} + + + + + + +LanguageDirection +: {#langs_language_languagedirection} + + + + + + +Title +: {#langs_language_title} + + + + + + +Weight +: {#langs_language_weight} + + + + + + + + + + + + + + + + + + + + + + + + + + + +## Params {#langs_language_params} + +\(\) → [Params](/documentation/reference/objects/common/maps/params) +{.funcsig} +Params returns language-specific params merged with the global params. + + + + + + + + + + + + diff --git a/exampleSite/content/en/documentation/reference/objects/media/type/index.md b/exampleSite/content/en/documentation/reference/objects/media/type/index.md new file mode 100644 index 0000000..80816a8 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/objects/media/type/index.md @@ -0,0 +1,111 @@ + + + +--- +title: "MediaType" +linkTitle: "MediaType" +description: "MediaType is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + + + +--- + + + + + + + + + + +## MainType {#media_type_maintype} +`MainType` is a [string](/documentation/reference/gotypes/#string). + + + + + + +## SubType {#media_type_subtype} +`SubType` is a [string](/documentation/reference/gotypes/#string). + + + + + + +## Delimiter {#media_type_delimiter} +`Delimiter` is a [string](/documentation/reference/gotypes/#string). + + + + + + +## FirstSuffix {#media_type_firstsuffix} +`FirstSuffix` is a [SuffixInfo](/documentation/reference/objects//suffixinfo). +FirstSuffix holds the first suffix defined for this Type. + + + + + + + + + + + + +## IsText {#media_type_istext} + +\(\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +IsText returns whether this Type is a text format. +Note that this may currently return false negatives. +TODO(bep) improve + + + + + + + + + + + + + + +## Suffixes {#media_type_suffixes} + +\(\) → [](/documentation/reference/objects//) +{.funcsig} +Suffixes returns all valid file suffixes for this type. + + + + + + + + +## Type {#media_type_type} + +\(\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Type returns a string representing the main- and sub-type of a media type, e.g. "text/css". +A suffix identifier will be appended after a "+" if set, e.g. "image/svg+xml". +Hugo will register a set of default media types. +These can be overridden by the user in the configuration, +by defining a media type with the same Type. + + + + + + diff --git a/exampleSite/content/en/documentation/reference/objects/navigation/_index.md b/exampleSite/content/en/documentation/reference/objects/navigation/_index.md new file mode 100644 index 0000000..486fed1 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/objects/navigation/_index.md @@ -0,0 +1,3 @@ +--- +title: Navigation +--- diff --git a/exampleSite/content/en/documentation/reference/objects/navigation/menus/index.md b/exampleSite/content/en/documentation/reference/objects/navigation/menus/index.md new file mode 100644 index 0000000..0a8a776 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/objects/navigation/menus/index.md @@ -0,0 +1,311 @@ + + + +--- +title: "Menus" +linkTitle: "Menus" +description: "Menus is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + +keywords: +- menu +- menus +- navigation + + +--- + + + +`Menu` is a slice of [](#navigation_) objects. + + + + + + + + + + +## ByName {#navigation_menu_byname} + +\(\) → [Menu](/documentation/reference/objects//menu) +{.funcsig} +ByName sorts the menu by the name defined in the menu configuration. + + + + + + + + +## ByWeight {#navigation_menu_byweight} + +\(\) → [Menu](/documentation/reference/objects//menu) +{.funcsig} +ByWeight sorts the menu by the weight defined in the menu configuration. + + + + + + + + + + +## Limit {#navigation_menu_limit} + +\([int](/documentation/reference/gotypes/#int)\) → [Menu](/documentation/reference/objects//menu) +{.funcsig} +Limit limits the returned menu to n entries. + + + + + + + + +## Reverse {#navigation_menu_reverse} + +\(\) → [Menu](/documentation/reference/objects//menu) +{.funcsig} +Reverse reverses the order of the menu entries. + + + + + + + + +## Sort {#navigation_menu_sort} + +\(\) → [Menu](/documentation/reference/objects//menu) +{.funcsig} +Sort sorts the menu by weight, name and then by identifier. + + + + + + + + + + + + + +ConfiguredURL +: The URL value from front matter / config. + +{#navigation_menuentry_configuredurl} + + + + + + +Page +: The [Page](/documentation/reference/objects/resources/page/page) connected to this menu entry. + +{#navigation_menuentry_page} + + + + + + +PageRef +: The path to the page, only relevant for menus defined in site config. + +{#navigation_menuentry_pageref} + + + + + + +Name +: The name of the menu entry. + +{#navigation_menuentry_name} + + + + + + +Menu +: The menu containing this menu entry. + +{#navigation_menuentry_menu} + + + + + + +Identifier +: Used to identify this menu entry. + +{#navigation_menuentry_identifier} + + + + + + +Pre +: If set, will be rendered before this menu entry. + +{#navigation_menuentry_pre} + + + + + + +Post +: If set, will be rendered after this menu entry. + +{#navigation_menuentry_post} + + + + + + +Weight +: The weight of this menu entry, used for sorting. +Set to a non-zero value, negative or positive. + +{#navigation_menuentry_weight} + + + + + + +Parent +: Identifier of the parent menu entry. + +{#navigation_menuentry_parent} + + + + + + +Children +: Child entries. + +{#navigation_menuentry_children} + + + + + + +Params +: User defined params. + +{#navigation_menuentry_params} + + + + + + + + + + + +## HasChildren {#navigation_menuentry_haschildren} + +\(\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +HasChildren returns whether this menu item has any children. + + + + + + + + +## IsEqual {#navigation_menuentry_isequal} + +\([](/documentation/reference/objects//)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +IsEqual returns whether the two menu entries represents the same menu entry. + + + + + + + + +## IsSameResource {#navigation_menuentry_issameresource} + +\([](/documentation/reference/objects//)\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +IsSameResource returns whether the two menu entries points to the same +resource (URL). + + + + + + + + +## KeyName {#navigation_menuentry_keyname} + +\(\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +KeyName returns the key used to identify this menu entry. + + + + + + + + + + +## Title {#navigation_menuentry_title} + +\(\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} + + + + + + + +## URL {#navigation_menuentry_url} + +\(\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} + + + + + +Menus is a map from string to [Menu](#navigation_menu). + + + + + + diff --git a/exampleSite/content/en/documentation/reference/objects/site/index.md b/exampleSite/content/en/documentation/reference/objects/site/index.md new file mode 100644 index 0000000..178e8a7 --- /dev/null +++ b/exampleSite/content/en/documentation/reference/objects/site/index.md @@ -0,0 +1,153 @@ + + + +--- +title: "Site" +linkTitle: "Site" +description: "Site is Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +hugoSymbol: TODO + + +keywords: +- site + +weight: 10 +--- + + + + + + + + +## Language {#page_site_language} +\(\) → [](/documentation/reference/objects//) +{.funcsig} +Returns the `Language` configured for this Site. + + + + +## RegularPages {#page_site_regularpages} +\(\) → [Pages](/documentation/reference/objects//pages) +{.funcsig} +Returns all the regular Pages in this Site. + + + + +## Pages {#page_site_pages} +\(\) → [Pages](/documentation/reference/objects//pages) +{.funcsig} +Returns all `Pages` in this Site. + + + + +## Home {#page_site_home} +\(\) → [Page](/documentation/reference/objects//page) +{.funcsig} +A shortcut to the home page. + + + + +## IsServer {#page_site_isserver} +\(\) → [bool](/documentation/reference/gotypes/#bool) +{.funcsig} +Returns true if we're running in a server. + + + + +## ServerPort {#page_site_serverport} +\(\) → [int](/documentation/reference/gotypes/#int) +{.funcsig} +Returns the server port. + + + + +## Title {#page_site_title} +\(\) → [string](/documentation/reference/gotypes/#string) +{.funcsig} +Returns the configured title for this Site. + + + + +## Sites {#page_site_sites} +\(\) → [Sites](/documentation/reference/objects//sites) +{.funcsig} +Returns all `Sites` for all languages. + + + + +## Current {#page_site_current} +\(\) → [Site](/documentation/reference/objects//site) +{.funcsig} +Returns Site currently rendering. + + + + +## Hugo {#page_site_hugo} +\(\) → [Info](/documentation/reference/objects/common/hugo/info) +{.funcsig} +Returns a struct with some information about the build. + + + + +## BaseURL {#page_site_baseurl} +\(\) → [URL](/documentation/reference/objects/html/template/url) +{.funcsig} +Returns the `BaseURL` for this Site. + + + + +## Taxonomies {#page_site_taxonomies} +\(\) → [any](/documentation/reference/gotypes/#any) +{.funcsig} +Retuns a taxonomy map. + + + + +## LastChange {#page_site_lastchange} +\(\) → [time.Time](/documentation/reference/gotypes/#timetime) +{.funcsig} +Returns the last modification date of the content. + + + + +## Menus {#page_site_menus} +\(\) → [Menus](/documentation/reference/objects/navigation/menus) +{.funcsig} +Returns the `Menus` for this site. + + + + +## Params {#page_site_params} +\(\) → [Params](/documentation/reference/objects/common/maps/params) +{.funcsig} +Returns the `Params` configured for this site. + + + + +## Data {#page_site_data} +\(\) → [](/documentation/reference/objects//) +{.funcsig} +Returns a map of all the data inside /data. + + + + + + diff --git a/exampleSite/content/en/documentation/tutorials/_index.md b/exampleSite/content/en/documentation/tutorials/_index.md new file mode 100644 index 0000000..c1451b6 --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/_index.md @@ -0,0 +1,4 @@ +--- +title: "Tutorials" +weight: 30 +--- diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/_index.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/_index.md new file mode 100644 index 0000000..a5bd070 --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/_index.md @@ -0,0 +1,16 @@ +--- +title: Hosting & Deployment +linktitle: Hosting & Deployment +description: Site builds, automated deployments, and popular hosting solutions. +date: 2016-11-01 +publishdate: 2016-11-01 +lastmod: 2016-11-01 +categories: [hosting and deployment] +keywords: [] +weight: 01 #rem +draft: false +aliases: [] +toc: false +--- + +Because Hugo renders *static* websites, you can host your new Hugo website virtually anywhere. The following represent only a few of the more popular hosting and automated deployment solutions used by the Hugo community. diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/deployment-with-nanobox.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/deployment-with-nanobox.md new file mode 100644 index 0000000..aac0744 --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/deployment-with-nanobox.md @@ -0,0 +1,246 @@ +--- +title: Host-Agnostic Deploys with Nanobox +linktitle: Host-Agnostic Deploys with Nanobox +description: Easily deploy Hugo to AWS, DigitalOcean, Google, Azure, and more... +date: 2017-08-24 +publishdate: 2017-08-24 +lastmod: 2017-08-24 +categories: [hosting and deployment] +keywords: [nanobox,deployment,hosting,aws,digitalocean,azure,google,linode] +authors: [Steve Domino] + +weight: 05 +sections_weight: 05 +draft: false +aliases: [/tutorials/deployment-with-nanobox/] +toc: true +--- + + + +Nanobox provides an entire end-to-end workflow for developing and deploying applications. Using Nanobox to deploy also means you'll use it to develop your application. + +{{% note %}} +If you're already using Nanobox and just need deployment instructions, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox) +{{% /note %}} + + +## What You'll Need + +With Nanobox you don't need to worry about having Go or Hugo installed. They'll be installed as part of the development environment created for you. + +To get started you'll just need the following three items: + +* [A Nanobox Account](https://nanobox.io) - Signup is free +* [Nanobox Desktop](https://dashboard.nanobox.io/download) - The free desktop development tool +* An account with a hosting provider such as: + - [AWS](https://docs.nanobox.io/providers/hosting-accounts/aws/) + - [Google](https://docs.nanobox.io/providers/hosting-accounts/gcp/) + - [Azure](https://docs.nanobox.io/providers/hosting-accounts/azure/) + - [DigitalOcean](https://docs.nanobox.io/providers/hosting-accounts/digitalocean/) + - [Linode](https://docs.nanobox.io/providers/hosting-accounts/linode/) + - [More...](https://docs.nanobox.io/providers/hosting-accounts/) + - [Roll Your Own](https://docs.nanobox.io/providers/create/) + +### Before You Begin + +There are a few things to get out of the way before diving into the guide. To deploy, you'll need to make sure you have connected a host account to your Nanobox account, and launched a new application. + +#### Connect a Host Account + +Nanobox lets you choose where to host your application (AWS, DigitalOcean, Google, Azure, etc.). In the [Hosting Accounts](https://dashboard.nanobox.io/provider_accounts) section of your Nanobox dashboard [link your Nanobox account with your host](https://docs.nanobox.io/providers/hosting-accounts/). + +#### Launch a New Application on Nanobox + +[Launching a new app on Nanobox](https://docs.nanobox.io/workflow/launch-app/) is very simple. Navigate to [Launch New App](https://dashboard.nanobox.io/apps/new) in the dashboard, and follow the steps there. You'll be asked to name your app, and to select a host and region. + +With those out of the way you're ready to get started! + + +## Getting Started + +{{% note %}} +If you already have a functioning Hugo app, you can skip to [Configure Hugo to run with Nanobox](#configure-hugo-to-run-with-nanobox) +{{% /note %}} + +To get started, all you'll need is an empty project directory. Create a directory wherever you want your application to live and `cd` into it: + +`mkdir path/to/project && cd path/to/project` + +### Configure Hugo to run with Nanobox + +Nanobox uses a simple config file known as a [boxfile.yml](https://docs.nanobox.io/boxfile/) to describe your application's infrastructure. In the root of your project add the following `boxfile.yml`: + +{{< code file="boxfile.yml" >}} +run.config: + + # use the static engine + engine: static + engine.config: + + # tell the engine where to serve static assets from + rel_dir: public + + # enable file watching for live reload + fs_watch: true + + # install hugo + extra_steps: + - bash ./install.sh + +deploy.config: + + # generate site on deploy + extra_steps: + - hugo + +{{< /code >}} + +{{% note %}} +If you already have a functioning Hugo app, after adding the boxfile, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox). +{{% /note %}} + +### Installing Hugo + +Nanobox uses Docker to create instant, isolated, development environments. Because of this, you'll need to make sure that during development you have Hugo available. + +Do this by adding a custom install script at the root of your project that will install Hugo automatically for you: + +{{< code file="install.sh" >}} + +#!/bin/bash + +if [[ ! -f /data/bin/hugo ]]; then + cd /tmp + wget https://github.com/gohugoio/hugo/releases/download/v0.31.1/hugo_0.31.1_Linux-64bit.tar.gz + tar -xzf hugo_0.31.1_Linux-64bit.tar.gz + mv hugo /data/bin/hugo + cd - + rm -rf /tmp/* +fi + +{{< /code >}} + +{{% note %}} +If the install script fails during `nanobox run` you may need to make it executable with `chmod +x install.sh` +{{% /note %}} +{{% note %}} +Make sure to check the version of Hugo you have installed and update the install script to match. +{{% /note %}} + +### Generating a New Hugo App + +You'll generate your new application from inside the Nanobox VM (this is why you don't need to worry about having Go or Hugo installed). + +Run the following command to drop into a Nanobox console (inside the VM) where your codebase is mounted: + +``` +nanobox run +``` + + + +Once inside the console use the following steps to create a new Hugo application: + +``` +# cd into the /tmp dir to create an app +cd /tmp + +# generate the hugo app +hugo new site app + +# cd back into the /app dir +cd - + +# copy the generated app into the project +shopt -s dotglob +cp -a /tmp/app/* . +``` + +### Install a theme + +`cd` into the `themes` directory and clone the `nanobox-hugo-theme` repo: + +``` +cd themes +git clone https://github.com/sdomino/nanobox-hugo-theme +``` + +To use the theme *either* copy the entire `config.toml` that comes with the theme, or just add the theme to your existing `config.toml` + +``` +# copy the config.toml that comes with the theme +cp ./themes/nanobox-hugo-theme/config.toml config.toml + +# or, add it to your existing config.toml +theme = "nanobox-hugo-theme" +``` + +{{% note %}} +It is not intended that you use the `nanobox-hugo-theme` as your actual theme. It's simply a theme to start with and should be replaced. +{{% /note %}} + +### View Your App + +To view your application simply run the following command from a Nanobox console: + +``` +hugo server --bind="0.0.0.0" --baseUrl=$APP_IP +``` + + + +With that you should be able to visit your app at the given IP:1313 address + +{{% note %}} +You can [add a custom DNS alias](https://docs.nanobox.io/cli/dns/#add) to make it easier to access your app. Run `nanobox dns add local hugo.dev`. After starting your server, visit your app at [hugo.dev:1313](http://hugo.dev:1313) +{{% /note %}} + +### Develop, Develop, Develop + +{{% note %}} +IMPORTANT: One issue we are aware of, and actively investigating, is livereload. Currently, livereload does not work when developing Hugo applications with Nanobox. +{{% /note %}} + +With Hugo installed you're ready to go. Develop Hugo like you would normally (using all the generators, etc.). Once your app is ready to deploy, run `hugo` to generate your static assets and get ready to deploy! + + +## Deploying Hugo with Nanobox + +{{% note %}} +If you haven't already, make sure to [connect a hosting account](#connect-a-host-account) to your Nanobox account, and [launch a new application](#launch-a-new-application-on-nanobox) in the Dashboard. +{{% /note %}} + +To deploy your application to Nanobox you simply need to [link your local codebase](https://docs.nanobox.io/workflow/deploy-code/#add-your-live-app-as-a-remote) to an application you've created on Nanobox. That is done with the following command: + +``` +nanobox remote add <your-app-name> +``` + +{{% note %}} +You may be prompted to login using your ***Nanobox credentials*** at this time +{{% /note %}} + +### Stage Your Application (optional) + +Nanobox gives you the ability to [simulate your production environment locally](https://docs.nanobox.io/workflow/deploy-code/#preview-locally). While staging is optional it's always recommended, so there's no reason not to! + +To stage your app simply run: + +``` +nanobox deploy dry-run +``` + +Now visit your application with the IP address provided. + + + +### Deploy Your Application + +Once everything checks out and you're [ready to deploy](https://docs.nanobox.io/workflow/deploy-code/#deploy-to-production), simply run: + +``` +nanobox deploy +``` + +Within minutes you're Hugo app will be deployed to your host and humming along smoothly. That's it! diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/deployment-with-rsync.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/deployment-with-rsync.md new file mode 100644 index 0000000..ef7fc0e --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/deployment-with-rsync.md @@ -0,0 +1,154 @@ +--- +title: Deployment with Rsync +linktitle: Deployment with Rsync +description: If you have access to your web host with SSH, you can use a simple rsync one-liner to incrementally deploy your entire Hugo website. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2019-10-03 +categories: [hosting and deployment] +keywords: [rsync,deployment] +authors: [Adrien Poupin] + +weight: 70 +sections_weight: 70 +draft: false +aliases: [/tutorials/deployment-with-rsync/] +toc: true +notesforauthors: +--- + +## Assumptions + +* A web host running a web server. This could be a shared hosting environment or a VPS. +* Access to your web host with SSH +* A functional static website built with Hugo + +The spoiler is that you can deploy your entire website with a command that looks like the following: + +``` +hugo && rsync -avz --delete public/ www-data@ftp.topologix.fr:~/www/ +``` + +As you will see, we'll put this command in a shell script file, which makes building and deployment as easy as executing `./deploy`. + +## Copy Your SSH Key to your Host + +To make logging in to your server more secure and less interactive, you can upload your SSH key. If you have already installed your SSH key to your server, you can move on to the next section. + +First, install the ssh client. On Debian/Ubuntu/derivates, use the following command: + +{{< code file="install-openssh.sh" >}} +sudo apt-get install openssh-client +{{< /code >}} + +Then generate your ssh key. First, create the `.ssh` directory in your home directory if it doesn't exist: + +``` +~$ cd && mkdir .ssh & cd .ssh +``` + +Next, execute this command to generate a new keypair called `rsa_id`: + +``` +~/.ssh/$ ssh-keygen -t rsa -q -C "For SSH" -f rsa_id +``` + +You'll be prompted for a passphrase, which is an extra layer of protection. Enter the passphrase you'd like to use, and then enter it again when prompted, or leave it blank if you don't want to have a passphrase. Not using a passphrase will let you transfer files non-interactively, as you won't be prompted for a password when you log in, but it is slightly less secure. + +To make logging in easier, add a definition for your web host to the file `~/.ssh/config` with the following command, replacing `HOST` with the IP address or hostname of your web host, and `USER` with the username you use to log in to your web host when transferring files: + +``` +~/.ssh/$ cat >> config <<EOF +Host HOST + Hostname HOST + Port 22 + User USER + IdentityFile ~/.ssh/rsa_id +EOF +``` + +Then copy your ssh public key to the remote server with the `ssh-copy-id` command: + +``` +~/.ssh/$ ssh-copy-id -i rsa_id.pub USER@HOST.com +``` + +Now you can easily connect to the remote server: + +``` +~$ ssh user@host +Enter passphrase for key '/home/mylogin/.ssh/rsa_id': +``` + +Now that you can log in with your SSH key, let's create a script to automate deployment of your Hugo site. + +## Shell Script + +Create a new script called `deploy` the root of your Hugo tree: + +``` +~/websites/topologix.fr$ editor deploy +``` + +Add the following content. Replace the `USER`, `HOST`, and `DIR` values with your own values: + +``` +#!/bin/sh +USER=my-user +HOST=my-server.com +DIR=my/directory/to/topologix.fr/ # the directory where your web site files should go + +hugo && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} + +exit 0 +``` + +Note that `DIR` is the relative path from the remote user's home. If you have to specify a full path (for instance `/var/www/mysite/`) you must change `~/${DIR}` to `${DIR}` inside the command line. For most cases you should not have to. + +Save and close, and make the `deploy` file executable: + +``` +~/websites/topologix.fr$ chmod +x deploy +``` + +Now you only have to enter the following command to deploy and update your website: + +``` +~/websites/topologix.fr$ ./deploy +``` + +Your site builds and deploys: + +``` +Started building sites ... +Built site for language en: +0 draft content +0 future content +0 expired content +5 pages created +0 non-page files copied +0 paginator pages created +0 tags created +0 categories created +total in 56 ms +sending incremental file list +404.html +index.html +index.xml +sitemap.xml +cours-versailles/index.html +exercices/index.html +exercices/index.xml +exercices/barycentre-et-carres-des-distances/index.html +posts/ +posts/index.html +sujets/index.html +sujets/index.xml +sujets/2016-09_supelec-jp/index.html +tarifs-contact/index.html + +sent 9,550 bytes received 1,708 bytes 7,505.33 bytes/sec +total size is 966,557 speedup is 85.86 +``` + +You can incorporate other proprocessing tasks into this deployment script as well. diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/deployment-with-wercker.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/deployment-with-wercker.md new file mode 100644 index 0000000..afa25c4 --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/deployment-with-wercker.md @@ -0,0 +1,318 @@ +--- +title: Deployment with Wercker +linktitle: Deployment with Wercker +description: You can use a free tool called Wercker to automate deployments between your GitHub-hosted source and final website on GitHub pages. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [hosting and deployment] +keywords: [wercker,deployment,github,git] +authors: [Arjen Schwarz, Samuel Debruyn] + +weight: 60 +sections_weight: 60 +draft: false +aliases: [/tutorials/automated-deployments/] +toc: true +wip: false +notesforauthors: +--- + +## Goals + +By the end of this guide, you will have completed the following: + +* Creating a basic Hugo project and website +* Version controlling your project with Git +* Adding your project to GitHub +* Automating site deployments with a free tool called Wercker +* Deploying your website to GitHub Pages for free hosting + +## Assumptions + +1. You have a working familiarity with using Git for version control +2. You have a GitHub account +3. You have already created a basic Hugo project + +If you do not meet these assumptions, the [GitHub help section][githubhelp] has an explanation of how to install and use git. [Signing up for a GitHub][ghsignup] account is free as well. If you are completely unfamiliar with creating a new Hugo website, visit the [Hugo Quick Start][quickstart]. + +## Create a Basic Hugo Site + +{{% note "This Guide Uses the Hugo CLI" %}} +All the work for setting up a Hugo project and using this guide is done via the Hugo CLI's most basic commands. See the [command line reference page](/commands/) for a more exhaustive account of the CLI's features. +{{% /note %}} + +First, create your new Hugo website using the [`hugo new site` command][basicusage] and change into the newly created directory for the project. In this guide, we are calling our new project `hugo-wercker-example`: + +{{< code file="hugo-new-site.sh" >}} +hugo new site hugo-wercker-example +cd hugo-wercker-example +{{< /code >}} + +We will use the [Herring Cove theme][] by first cloning the theme into the `themes` directory. + +{{< code file="clone-herring-cove-theme.sh" >}} +cd themes +git clone https://github.com/spf13/herring-cove.git +{{< /code >}} + +Cloning the project from the command line will conflict with our own version control. So, we need to remove the external git configuration that came with the clone of Herring Cove: + +{{< code file="remove-herring-cove-git.sh" >}} +rm -rf herring-cove/.git +{{< /code >}} + +We need content for Hugo to build. Let's add a quick `/about` page: + +``` +hugo new about.md +``` + +{{% note %}} +The preceding example for the about page leverages archetypes to scaffold a new content file with preconfigured front matter. [Find out more about Hugo's archetypes](/content-management/archetypes/). +{{% /note %}} + +Now you can edit `contents/about.md` in your text editor of choice, but this is not necessary for the purposes of this guide. Running the following command will build your Hugo site into the `public` directory. + +Once the website is build, it's a good idea to run the following command to start a local server and ensure you're changes have been implemented: + +``` +hugo server --theme=herring-cove +``` + +If everything is fine, you should see something similar to the image below when you go to <http://localhost:1313> in your browser. + +![][1] + +## Set up Version Control in Git + +Adding Git to your project is done by running the `git init` command from the root directory of your project. + +``` +git init +``` + +Running `git status` at this point will show you the following entries: the `config.toml` file, the `themes` directory, the `contents` directory, and the `public` directory. However, we don't want the `public` directory version controlled because Wercker is responsible for generating the finished website later on. Therefore, we'll add a `.gitignore` file to our project that will exclude the `/public` directory from being tracked by Git: + +{{< code file="gitignore.sh" >}} +echo "/public" >> .gitignore +{{< /code >}} + +Wercker might complain when we try to build the site later on because we currently do not have any static files outside of the `themes` directory. We simply have to add *any* file to the static folder to prevent Wercker from complaining. To keep this guide simple, let's add a `robots.txt`. The following command creates the file in `/static`. The contents of the `robots.txt` lets search engines know they have full access to crawl the published website: + +{{< code file="addrobotstxt.sh" >}} +echo "User-agent: *\nDisallow:" > static/robots.txt +{{< /code >}} + +Now we need to add (i.e., [stage [see Git documentation]][gitbasics]) and commit all of our changes in the repository into Git: + +``` +git commit -a -m "Initial commit" +``` + +## Add the Project to GitHub + +Now we need to create a new repository on GitHub. Once you are signed in to GitHub, you can add a new repository by clicking on the **+▼** dropdown at the top right or by going to [https://github.com/new](https://github.com).. + +We then choose a name for the project (`hugo-wercker-example`). When clicking on create repository GitHub displays the commands for adding an existing project to the site. The commands shown below are the ones used for this site, if you're following along you will need to use the ones shown by GitHub. Once we've run those commands the project is in GitHub and we can move on to setting up the Wercker configuration. Be sure to replace `YourUserName` with your GitHub account/username: + +{{< code file="setup-gh-repo.sh" >}} +git remote add origin git@github.com:YourUsername/hugo-wercker-example.git +git push -u origin master +{{< /code >}} + +![][2] + +## Set Up Wercker + +To sign up for a free Wercker account, go to <https://www.wercker.com> and click the **Sign Up** button on the top right of the home screen. + +![][3] + +### Register for Wercker with Your GitHub Account + +Sign up for Wercker using your GitHub credentials. If you don't have a GitHub account, or don't want to use it for your account, you have the option to register with a username and password as well. However, the second half of this guide---devoted to hosting your website on GitHub pages---will no longer be of interest to you. + +![][4] + +### Connect GitHub or Bitbucket + +After you are registered, you will need to link your GitHub or Bitbucket account to Wercker. You can link your account by navigating to your profile settings and then selecting "Git connections." + +![][17] + +If you registered for Wercker using GitHub, it will most likely look like the following image. To connect a missing service, click the **Connect** button, which may send you to either GitHub or Bitbucket to sign into your respective account. + +![][5] + +### Add Your Project + +Now that we've got all the preliminaries out of the way, it's time to set up our application. For this we click on the **+ Create** button next to Applications and choose GitHub as our provider. + +![][6] + +### Select a Repository + +When selecting GitHub, Wercker will show all your GitHub repositories. You have the option to filter repositories using the search input at the top of the repositories list. Once you have your repository selected, click the **Use selected repo** button. + +![][7] + +### Select the Repository Owner + +In the next step, Wercker asks you to select the repository owner. Select your GitHub account and continue. + +![][8] + +### Configure Access + +{{% note %}} +This guide assumes you are using a public GitHub repository and understand that the [published GitHub Pages website will be available to everyone](https://help.github.com/articles/what-is-github-pages/#usage-limits). +{{%/note %}} + +This step can be slightly tricky. Wercker does not have privileges to check out your private projects by default and therefore needs your permission to add a deploy key to your repository. By selecting the first option, you're simply allowing Wercker to check out the code via the same methods available to anyone visiting the project on GitHub. + +![][9] + +### Wercker.yml + +Wercker will now attempt to create an initial `wercker.yml` file for you. More specifically, it will create a code block within the Wercker interface that you can copy to your finished file. Wercker gives us a `debian` box because our project does not have any special requirements. + +Now we need to create a *wercker.yml* file in the root of our project. This file will contain our Wercker app's configuration. After we finish setting up our app, we will expand the contents of this file to build and deploy our website. + +![][10] + +### Public or Private + +This is a personal choice. You can make an app public so that everyone can see more details about it. Keeping it private or public does not provide any overt benefits for you as the creator of the app. That said, [the app we are currently creating has been made public][publicappurl] to facilitate easier usage of this hosting and deployment guide. + +![][11] + +#### App Successfully Created + +The application is now added and Wercker will offer you the chance to trigger a build. However, we will decline the offer because we haven't yet pushed our `wercker.yml` file to our GitHub repository. + +![][12] + +### Add the Hugo-build Step + +Now we need to add the Wercker steps to our build process. First, we go to the "Registry" action in the top menu. When in the registry, we can search for "hugo build". Select the "Hugo-Build by **arjen**" step. + +![][13] + +### Use the Hugo-build Step + +A summary of very basic usage is available at the top of the details for the Hugo-Build step. Below the basic usage is the contents of the `README.md` file associated with the step's repository. `README.md`'s on Wercker usually contain more details about the advanced options and examples of usage. + +We're not going to use any of the advanced features of Hugo-Build in this guide. Let's return to our project and add the first section of details we need to our `wercker.yml`. + +{{% warning "Hugo Version in `wercker.yml`" %}} +The docs are a work in progress. As such, the `version` represented in this guide may not represent the version you've been using for local development. Be sure to use the appropriate Hugo version for your build step. +{{% /warning %}} + +{{< code file="wercker-build-step.yml" >}} +box: debian +build: + steps: + - arjen/hugo-build: + version: "0.17" + theme: herring-cove + flags: --buildDrafts=true +{{< /code >}} + +We can conclude this first step by pushing our `wercker.yml` to our GitHub repository and then seeing the magic at work within Wercker's interface. + +{{< code file="push-wecker-to-gh.sh" >}} +git commit -a -m "Add wercker.yml" +git push origin master +{{< /code >}} + +If completed and successful, a green check mark should appear in the commit column of your first build. However, this is only the build step. We still need to deploy the website to our free hosting on GitHub Pages. If you would like more details about the build, you can click the commit hash. + +![][14] + +### Add a GitHub Pages Deploy Step to `wercker.yml` + +In order to deploy to GitHub Pages, we need to add a deploy step to our `wercker.yml`. We are going to add `lukevevier/gh-pages`, the most popular GitHub Pages step in the Wercker Steps repository. Additionally, we need to ensure the box Wercker uses for our deployments has git and ssh installed. We can do this using the `install-packages` command. Here is our *final* `wercker.yml` file: + +{{< code file="wercker.yml" >}} +box: debian +build: + steps: + - arjen/hugo-build: + version: "0.17" + theme: herring-cove + flags: --buildDrafts=true +deploy: + steps: + - install-packages: + packages: git ssh-client + - lukevivier/gh-pages@0.2.1: + token: $GIT_TOKEN + domain: hugo-wercker.ig.nore.me + basedir: public +{{< /code >}} + +### How does the GitHub Pages Configuration Work? + +We've provided a some important information in our `wercker.yml`. First, we've added the domain we want to use for our published website. Configuring the domain here will ensure that GitHub Pages is aware of the domain we want to use. + +Secondly, we've configured the `basedir` to `public`. This is the directory that will be used as the website on GitHub Pages. `public` is also the default publishing directory in Hugo. (For more information, see [hugo's configuration docs][hugoconfig]). + +Lastly, you'll notice a `$GIT_TOKEN` variable. This is used for pushing our changes to GitHub. We will need to configure this token before Wercker can build our website. + +### Set the App's Deploy Target + +We can set our deploy target by going to our app's settings and clicking on **Deploy targets**. Now select **Add deploy target** and then **Custom deploy**. + +![][15] + +### Configure the Deploy Step in Wercker + +The next screen requires you fill in the deploy target name. + +1. Make sure you enable **auto deploy** from the **master** branch. +2. Add a variable for the **GIT_TOKEN**. You'll need to create an access token in GitHub. Follow the directions in [GitHub help][accesstokenghhelp]. +3. With the deploy step configured in Wercker, we can push the updated wercker.yml file to GitHub and it will create the GitHub pages site for us. + +The website described in this guide is available at <http://hugo-wercker.ig.nore.me>. + +![][16] + +## Conclusion + +Once this workflow is established, you can update your website automatically by pushing any content changes to your GitHub repository. + +### Code for the Wercker Deployment Guide + +[The source code for the site used in this guide is available on GitHub][guidesource], as is the [Wercker Hugo Build step][guidestep]. + +[1]: /images/hosting-and-deployment/deployment-with-wercker/creating-a-basic-hugo-site.png +[2]: /images/hosting-and-deployment/deployment-with-wercker/adding-the-project-to-github.png +[3]: /images/hosting-and-deployment/deployment-with-wercker/wercker-sign-up.png +[4]: /images/hosting-and-deployment/deployment-with-wercker/wercker-sign-up-page.png +[5]: /images/hosting-and-deployment/deployment-with-wercker/wercker-git-connections.png +[6]: /images/hosting-and-deployment/deployment-with-wercker/wercker-add-app.png +[7]: /images/hosting-and-deployment/deployment-with-wercker/wercker-select-repository.png +[8]: /images/hosting-and-deployment/deployment-with-wercker/wercker-select-owner.png +[9]: /images/hosting-and-deployment/deployment-with-wercker/wercker-access.png +[10]: /images/hosting-and-deployment/deployment-with-wercker/werckeryml.png +[11]: /images/hosting-and-deployment/deployment-with-wercker/public-or-not.png +[12]: /images/hosting-and-deployment/deployment-with-wercker/and-we-ve-got-an-app.png +[13]: /images/hosting-and-deployment/deployment-with-wercker/wercker-search.png +[14]: /images/hosting-and-deployment/deployment-with-wercker/using-hugo-build.png +[15]: /images/hosting-and-deployment/deployment-with-wercker/adding-a-github-pages-step.png +[16]: /images/hosting-and-deployment/deployment-with-wercker/configure-the-deploy-step.png +[17]: /images/hosting-and-deployment/deployment-with-wercker/wercker-account-settings.png + + +[accesstokenghhelp]: https://help.github.com/articles/creating-an-access-token-for-command-line-use/ +[basicusage]: /getting-started/usage/ +[ghsignup]: https://github.com/join +[gitbasics]: https://git-scm.com/book/en/v2/Getting-Started-Git-Basics +[githubhelp]: https://help.github.com/articles/set-up-git/ +[guidesource]: https://github.com/ArjenSchwarz/hugo-wercker-example +[guidestep]: https://github.com/ArjenSchwarz/wercker-step-hugo-build +[Herring Cove theme]: https://github.com/spf13/herring-cove +[hugoconfig]: /getting-started/configuration/ +[publicappurl]: https://app.wercker.com/#applications/5586dcbdaf7de9c51b02b0d5 +[quickstart]: /getting-started/quick-start/ diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-aws-amplify.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-aws-amplify.md new file mode 100644 index 0000000..9ffae5d --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-aws-amplify.md @@ -0,0 +1,54 @@ +--- +title: Host on AWS Amplify +linktitle: Host on AWS Amplify +description: Develop and deploy a cloud-powered web app with AWS Amplify. +date: 2018-01-31 +publishdate: 2018-01-31 +lastmod: 2018-01-31 +categories: [hosting and deployment] +keywords: [amplify,hosting,deployment] +authors: [Nikhil Swaminathan] + +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +--- + +In this guide we'll walk through how to deploy and host your Hugo site using the [AWS Amplify Console](https://console.amplify.aws). + +AWS Amplify is a combination of client library, CLI toolchain, and a Console for continuous deployment and hosting. The Amplify CLI and library allow developers to get up & running with full-stack cloud-powered applications with features like authentication, storage, serverless GraphQL or REST APIs, analytics, Lambda functions, & more. The Amplify Console provides continuous deployment and hosting for modern web apps (single page apps and static site generators). Continuous deployment allows developers to deploy updates to their web app on every code commit to their Git repository. Hosting includes features such as globally available CDNs, easy custom domain setup + HTTPS, feature branch deployments, and password protection. + +## Pre-requisites + +* [Sign up for an AWS Account](https://portal.aws.amazon.com/billing/signup?redirect_url=https%3A%2F%2Faws.amazon.com%2Fregistration-confirmation). There are no upfront charges or any term commitments to create an AWS account and signing up gives you immediate access to the AWS Free Tier. +* You have an account with GitHub, GitLab, or Bitbucket. +* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world. + +## Hosting + +1. Log in to the [AWS Amplify Console](https://console.aws.amazon.com/amplify/home) and choose Get Started under Deploy. +  + +1. Connect a branch from your GitHub, Bitbucket, GitLab, or AWS CodeCommit repository. Connecting your repository allows Amplify to deploy updates on every code commit to a branch. +  + +1. Accept the default build settings. The Amplify Console automatically detects your Hugo build settings and output directory. +  + +1. Review your changes and then choose **Save and deploy**. The Amplify Console will pull code from your repository, build changes to the backend and frontend, and deploy your build artifacts at `https://master.unique-id.amplifyapp.com`. Bonus: Screenshots of your app on different devices to find layout issues. + +## Using a Newer Version of Hugo + +If you need to use a different, perhaps newer, version of Hugo than the version currently supported by AWS Amplify: + +1. Visit the [AWS Amplify Console](https://console.aws.amazon.com/amplify/home), and click the app you would like to modify +1. In the side navigation bar, Under App Settings, click **Build settings** +1. On the Build settings page, near the bottom, there is a section called **Build image settings**. Click **Edit** +1. Under **Live package updates**, click **Add package version override** +1. From the selection, click **Hugo** and ensure the version field says `latest` +1. Click **Save** to save the changes. + + +[Quick Start]: /getting-started/quick-start/ diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-bitbucket.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-bitbucket.md new file mode 100644 index 0000000..b974a8e --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-bitbucket.md @@ -0,0 +1,138 @@ +--- +title: Host on Bitbucket +linktitle: Host on Bitbucket +description: You can use Bitbucket in conjunction with Aerobatic to build, deploy, and host a Hugo website. +date: 2017-02-04 +publishdate: 2017-02-04 +lastmod: 2017-02-04 +categories: [hosting and deployment] +keywords: [hosting,bitbucket,deployment,aerobatic] +authors: [Jason Gowans] + +weight: 50 +sections_weight: 50 +draft: false +toc: true +aliases: [/tutorials/hosting-on-bitbucket/] +--- + +You can use [Bitbucket](https://bitbucket.org/) and [Aerobatic](https://www.aerobatic.com) to build, deploy, and host a Hugo website. Aerobatic is a static hosting service that integrates with Bitbucket and provides a free hosting tier. + +## Assumptions + +* Working familiarity with Git for version control +* A [Bitbucket account](https://bitbucket.org/account/signup/) + +## Install Aerobatic CLI + +If you haven't previously used Aerobatic, you'll first need to install the Command Line Interface (CLI) and create an account. For a list of all commands available, see the [Aerobatic CLI](https://www.aerobatic.com/docs/cli/) docs. + +``` +npm install aerobatic-cli -g +aero register +``` + +## Create and Deploy Site + +``` +hugo new site my-new-hugo-site +cd my-new-hugo-site +cd themes; git clone https://github.com/eliasson/liquorice +hugo -t liquorice +aero create # create the Aerobatic site +hugo --baseURL https://my-new-hugo-site.aerobatic.io # build the site overriding baseURL +aero deploy -d public # deploy output to Aerobatic + +Version v1 deployment complete. +View now at https://hugo-docs-test.aerobatic.io +``` + +In the rendered page response, the `https://__baseurl__` will be replaced with your actual site url (in this example, `https://my-new-hugo-site.aerobatic.io`). You can always rename your Aerobatic website with the `aero rename` command. + +## Push Hugo site to Bitbucket + +We will now create a git repository and then push our code to Bitbucket. In Bitbucket, create a repository. + +![Bitbucket Screenshot][1] + +[1]: /images/hosting-and-deployment/hosting-on-bitbucket/bitbucket-create-repo.png + +``` +# initialize new git repository +git init + +# set up our .gitignore file +echo -e "/public \n/themes \naero-deploy.tar.gz" >> .gitignore + +# commit and push code to master branch +git add --all +git commit -m "Initial commit" +git remote add origin git@bitbucket.org:YourUsername/my-new-hugo-site.git +git push -u origin master +``` + +## Continuous Deployment With Bitbucket Pipelines + +In the example above, we pushed the compiled assets in the `/public` folder to Aerobatic. In the following example, we use Bitbucket Pipelines to continuously create and deploy the compiled assets to Aerobatic. + +### Step 1: Configure Bitbucket Pipelines + +In your Hugo website's Bitbucket repo; + +1. Click the Pipelines link in the left nav menu of your Bitbucket repository. +2. Click the Enable Pipelines button. +3. On the next screen, leave the default template and click Next. +4. In the editor, paste in the yaml contents below and click Commit. + +``` +image: beevelop/nodejs-python +pipelines: + branches: + master: + - step: + script: + - apt-get update -y && apt-get install wget + - apt-get -y install git + - wget https://github.com/gohugoio/hugo/releases/download/v0.18/hugo_0.18-64bit.deb + - dpkg -i hugo*.deb + - git clone https://github.com/eliasson/liquorice themes/liquorice + - hugo --theme=liquorice --baseURL https://__baseurl__ --buildDrafts + - npm install -g aerobatic-cli + - aero deploy +``` + +### Step 2: Create `AEROBATIC_API_KEY` environment variable. + +This step only needs to be done once per account. From the command line; + +``` +aero apikey +``` + +1. Navigate to the Bitbucket account settings for the account that the website repo belongs to. +2. Scroll down to the bottom of the left nav and click the Environment variables link in the PIPELINES section. +3. Create a new environment variable called AEROBATIC_API_KEY with the value you got by running the `aero apikey` command. Be sure to click the Secured checkbox. + +### Step 3: Edit and Commit Code + +``` +hugo new posts/good-to-great.md +hugo server --buildDrafts -t liquorice #Check that all looks good + +# commit and push code to master branch +git add --all +git commit -m "New blog post" +git push -u origin master +``` + +Your code will be committed to Bitbucket, Bitbucket Pipelines will run your build, and a new version of your site will be deployed to Aerobatic. + +At this point, you can now create and edit blog posts directly in the Bitbucket UI. + +![Bitbucket blog Screenshot][2] + +[2]: /images/hosting-and-deployment/hosting-on-bitbucket/bitbucket-blog-post.png + +## Suggested next steps + +The code for this example can be found in this Bitbucket [repository](https://bitbucket.org/dundonian/hugo-docs-test). Aerobatic also provides a number of additional [plugins](https://www.aerobatic.com/docs) such as auth and redirects that you can use for your Hugo site. diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-firebase.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-firebase.md new file mode 100644 index 0000000..1f77be3 --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-firebase.md @@ -0,0 +1,88 @@ +--- +title: Host on Firebase +linktitle: Host on Firebase +description: You can use Firebase's free tier to host your static website; this also gives you access to Firebase's NOSQL API. +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-15 +categories: [hosting and deployment] +keywords: [hosting,firebase] +authors: [Michel Racic] + +weight: 20 +sections_weight: 20 +draft: false +toc: true +aliases: [] +--- + +## Assumptions + +1. You have an account with [Firebase][signup]. (If you don't, you can sign up for free using your Google account.) +2. You have completed the [Quick Start][] or have a completed Hugo website ready for deployment. + +## Initial setup + +Go to the [Firebase console][console] and create a new project (unless you already have a project). You will need to globally install `firebase-tools` (node.js): + + +``` +npm install -g firebase-tools +``` + +Log in to Firebase (setup on your local machine) using `firebase login`, which opens a browser where you can select your account. Use `firebase logout` in case you are already logged in but to the wrong account. + + +``` +firebase login +``` +In the root of your Hugo project, initialize the Firebase project with the `firebase init` command: + +``` +firebase init +``` +From here: + +1. Choose Hosting in the feature question +2. Choose the project you just set up +3. Accept the default for your database rules file +4. Accept the default for the publish directory, which is `public` +5. Choose "No" in the question if you are deploying a single-page app + +## Deploy + +To deploy your Hugo site, execute the `firebase deploy` command, and your site will be up in no time: + +``` +hugo && firebase deploy +``` + +## CI Setup + +You can generate a deploy token using + + +``` +firebase login:ci +``` + +You can also set up your CI (e.g., with [Wercker][]) and add the token to a private variable like `$FIREBASE_DEPLOY_TOKEN`. + +{{% note %}} +This is a private secret and it should not appear in a public repository. Make sure you understand your chosen CI and that it's not visible to others. +{{% /note %}} + +You can then add a step in your build to do the deployment using the token: + +``` +firebase deploy --token $FIREBASE_DEPLOY_TOKEN +``` + +## Reference links + +* [Firebase CLI Reference](https://firebase.google.com/docs/cli/#administrative_commands) + +[console]: https://console.firebase.google.com +[Quick Start]: /getting-started/quick-start/ +[signup]: https://console.firebase.google.com/ +[Wercker]: /hosting-and-deployment/deployment-with-wercker/ diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-github.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-github.md new file mode 100644 index 0000000..2250d87 --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-github.md @@ -0,0 +1,101 @@ +--- +title: Host on GitHub +linktitle: Host on GitHub +description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with Github Action Workflow +date: 2014-03-21 +publishdate: 2014-03-21 +categories: [hosting and deployment] +keywords: [github,git,deployment,hosting] +authors: [Spencer Lyon, Gunnar Morling] + +weight: 30 +sections_weight: 30 +toc: true +aliases: [/tutorials/github-pages-blog/] +--- + +GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][] and automate development workflows and build with [GitHub Actions]. + +## Assumptions + +1. You have Git 2.8 or greater [installed on your machine][installgit]. +2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free. +3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][]. + +## Types of GitHub Pages + +There are two types of GitHub Pages: + +- User/Organization Pages (`https://<USERNAME|ORGANIZATION>.github.io/`) +- Project Pages (`https://<USERNAME|ORGANIZATION>.github.io/<PROJECT>/`) + +Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use. + +## GitHub User or Organization Pages + +As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations: + +1. You must use a `<USERNAME>.github.io` to host your **generated** content +2. Content from the `main` branch will be used to publish your GitHub Pages site + +This is a much simpler setup as your Hugo files and generated content are published into two different repositories. + +## Build Hugo With GitHub Action + +GitHub execute your software development workflows. Everytime you push your code on the Github repository, Github Action will build the site automatically. + +Create a file in `.github/workflows/gh-pages.yml` containing the following content (based on https://github.com/marketplace/actions/hugo-setup ): + +```yml +name: github pages + +on: + push: + branches: + - main # Set a branch to deploy + +jobs: + deploy: + runs-on: ubuntu-18.04 + steps: + - uses: actions/checkout@v2 + with: + submodules: true # Fetch Hugo themes (true OR recursive) + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: 'latest' + # extended: true + + - name: Build + run: hugo --minify + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./public +``` + +For more advanced settings https://github.com/marketplace/actions/hugo-setup + +## Use a Custom Domain + +If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirement of GitHub Pages. + +Refer to the [official documentation for custom domains][domains] for further information. + +[config]: /getting-started/configuration/ +[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/ +[ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages +[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ +[ghsignup]: https://github.com/join +[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/ +[installgit]: https://git-scm.com/downloads +[orphan branch]: https://git-scm.com/docs/git-checkout/#Documentation/git-checkout.txt---orphanltnewbranchgt +[Quick Start]: /getting-started/quick-start/ +[submodule]: https://github.com/blog/2104-working-with-submodules +[worktree feature]: https://git-scm.com/docs/git-worktree +[GitHub Actions]: https://docs.github.com/en/actions diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-gitlab.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-gitlab.md new file mode 100644 index 0000000..d43871c --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-gitlab.md @@ -0,0 +1,85 @@ +--- +title: Host on GitLab +linktitle: Host on GitLab +description: GitLab makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo. +date: 2016-06-23 +publishdate: 2016-06-23 +lastmod: 2017-11-16 +categories: [hosting and deployment] +keywords: [hosting,deployment,git,gitlab] +authors: [Riku-Pekka Silvola] + +weight: 40 +sections_weight: 40 +draft: false +toc: true +wip: false +aliases: [/tutorials/hosting-on-gitlab/] +--- + +[GitLab](https://gitlab.com/) makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides [native support for Hugo, as well as numerous other static site generators](https://gitlab.com/pages/hugo). + +## Assumptions + +* Working familiarity with Git for version control +* Completion of the Hugo [Quick Start][] +* A [GitLab account](https://gitlab.com/users/sign_in) +* A Hugo website on your local machine that you are ready to publish + +## Create .gitlab-ci.yml + +``` +cd your-hugo-site +``` + +In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below. + +{{< code file=".gitlab-ci.yml" >}} +image: monachus/hugo + +variables: + GIT_SUBMODULE_STRATEGY: recursive + +pages: + script: + - hugo + artifacts: + paths: + - public + only: + - master +{{< /code >}} + +## Push Your Hugo Website to GitLab + +Next, create a new repository on GitLab. It is *not* necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control. + +``` +# initialize new git repository +git init + +# add /public directory to our .gitignore file +echo "/public" >> .gitignore + +# commit and push code to master branch +git add . +git commit -m "Initial commit" +git remote add origin https://gitlab.com/YourUsername/your-hugo-site.git +git push -u origin master +``` + +## Wait for Your Page to Build + +That's it! You can now follow the CI agent building your page at `https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines`. + +After the build has passed, your new website is available at `https://<YourUsername>.gitlab.io/<your-hugo-site>/`. + +{{% note %}} +Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitLab pages repository if you're using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain. +{{% /note %}} + +## Next Steps + +GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/). + +[Quick Start]: /getting-started/quick-start/ diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-keycdn.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-keycdn.md new file mode 100644 index 0000000..8d9cb0e --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-keycdn.md @@ -0,0 +1,94 @@ +--- +title: "Hosting on KeyCDN" +date: 2017-09-12 +description: "Accelerate your Hugo site globally with a KeyCDN integration. This tutorial shows you how to setup your static site as a GitLab page behind a KeyCDN pull zone." +categories: [hosting and deployment] +keywords: [keycdn,hosting,deployment,cdn] +menu: + docs: + parent: "hosting-and-deployment" + weight: 40 +slug: "" +aliases: [] +toc: false +draft: false +--- + +[KeyCDN](https://www.keycdn.com/) provides a multitude of features to help accelerate and secure your Hugo site globally including Brotli compression, Let's Encrypt support, Origin Shield, and more. + +## Assumptions + +- You already have a Hugo page configured +- You have a GitLab account +- You have a KeyCDN account + +## Create a KeyCDN Pull Zone + +The first step will be to login to your KeyCDN account and create a new zone. Name this whatever you like and select the [Pull Zone](https://www.keycdn.com/support/create-a-pull-zone/) option. As for the origin URL, your site will be running on [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_one.html) with a URL of `https://youruser.gitlab.io/reponame/`. Use this as the Origin URL. + + + +While the origin location doesn’t exist yet, you will need to use your new Zone URL address (or [Zone Alias](https://www.keycdn.com/support/create-a-zone-alias/)) in the `.gitlab-ci.yml` file that will be uploaded to your GitLab project. + +Ensure that you use your Zone URL or Zone alias as the `BASEURL` variable in the example below. This will be the user-visible website address. + +## Configure Your .gitlab-ci.yml File + +Your `.gitlab-ci.yml` file should look similar to the example below. Be sure to modify any variables that are specific to your setup. + +``` +image: alpine:latest + +variables: + BASEURL: "https://cipull-7bb7.kxcdn.com/" + HUGO_VERSION: "0.26" + HUGO_CHECKSUM: "67e4ba5ec2a02c8164b6846e30a17cc765b0165a5b183d5e480149baf54e1a50" + KEYCDN_ZONE_ID: "75544" + +before_script: + - apk update + - apk add curl + +pages: + stage: deploy + script: + - apk add git + - git submodule update --init + - curl -sSL https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz -o /tmp/hugo.tar.gz + - echo "${HUGO_CHECKSUM} /tmp/hugo.tar.gz" | sha256sum -c + - tar xf /tmp/hugo.tar.gz hugo -C /tmp/ && cp /tmp/hugo /usr/bin + - hugo --baseURL ${BASEURL} + - curl "https://api.keycdn.com/zones/purge/${KEYCDN_ZONE_ID}.json" -u "${KEYCDN_API_KEY}:" + artifacts: + paths: + - public + only: + - master + +``` +Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section. + +The Secret Variable for your Zone ID should look similar to: + + + +While the Secret Variable for your API Key will look similar to: + + + +The Zone ID and API key are used to purge your zone – it’s not strictly needed but otherwise, the CDN might deliver older versions of your assets for quite a while. + +## Push Your Changes to GitLab + +Now it’s time to push the newly created repository to GitLab: + +``` +git remote add origin git@gitlab.com:youruser/ciexample.git +git push -u origin master +``` + +You can watch the progress and CI job output in your Gitlab project under “Pipelines”. + +After verifying your CI job ran without issues, first check that your GitLab page shows up under `https://youruser.gitlab.io/reponame/` (it might look broken depending on your browser settings as all links point to your KeyCDN zone – don’t worry about that) and then by heading to whatever Zone alias / Zone URL you defined. + +To learn more about Hugo hosting options with KeyCDN, check out the complete [Hugo hosting with KeyCDN integration guide](https://www.keycdn.com/support/hugo-hosting/). diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-netlify.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-netlify.md new file mode 100644 index 0000000..3cfdafb --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-netlify.md @@ -0,0 +1,156 @@ +--- +title: Host on Netlify +linktitle: Host on Netlify +description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-11 +categories: [hosting and deployment] +keywords: [netlify,hosting,deployment] +authors: [Ryan Watters, Seth MacLeod] + +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +--- + +[Netlify][netlify] provides continuous deployment services, global CDN, ultra-fast DNS, atomic deploys, instant cache invalidation, one-click SSL, a browser-based interface, a CLI, and many other features for managing your Hugo website. + +## Assumptions + +* You have an account with GitHub, GitLab, or Bitbucket. +* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world. +* You do not already have a Netlify account. + +## Create a Netlify account + +Go to [app.netlify.com][] and select your preferred signup method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address. + +The following examples use GitHub, but other git providers will follow a similar process. + + + +Selecting GitHub will bring up an authorization modal for authentication. Select "Authorize application." + + + +## Create a New Site with Continuous Deployment + +You're now already a Netlify member and should be brought to your new dashboard. Select "New site from git." + + + +Netlify will then start walking you through the steps necessary for continuous deployment. First, you'll need to select your git provider again, but this time you are giving Netlify added permissions to your repositories. + + + +And then again with the GitHub authorization modal: + + + +Select the repo you want to use for continuous deployment. If you have a large number of repositories, you can filter through them in real time using repo search: + + + +Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you wanted published, your [build command][], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch. + +## Configure Hugo Version in Netlify + +You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for your environments in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console. + +For production: + +``` +[context.production.environment] + HUGO_VERSION = "0.53" +``` + +For testing: + +``` +[context.deploy-preview.environment] + HUGO_VERSION = "0.53" +``` + +The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`: + +{{< code file="netlify.toml" nocode="true" >}} +{{< readfile file="netlify.toml" highlight="toml" >}} +{{< /code >}} + +## Build and Deploy Site + +In the Netlify console, selecting "Deploy site" will immediately take you to a terminal for your build:. + + + +Once the build is finished---this should only take a few seconds--you should now see a "Hero Card" at the top of your screen letting you know the deployment is successful. The Hero Card is the first element that you see in most pages. It allows you to see a quick summary of the page and gives access to the most common/pertinent actions and information. You'll see that the URL is automatically generated by Netlify. You can update the URL in "Settings." + + + + + +[Visit the live site][visit]. + +Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site. + +See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions. + +## Use Hugo Themes with Netlify + +The [`git clone` method for installing themes][installthemes] is not supported by Netlify. If you were to use `git clone`, it would require you to recursively remove the `.git` subdirectory from the theme folder and would therefore prevent compatibility with future versions of the theme. + +A *better* approach is to install a theme as a proper git submodule. You can [read the GitHub documentation for submodules][ghsm] or those found on [Git's website][gitsm] for more information, but the command is similar to that of `git clone`: + +``` +cd themes +git submodule add https://github.com/<THEMECREATOR>/<THEMENAME> +``` + +It is recommended to only use stable versions of a theme (if it’s versioned) and always check the changelog. This can be done by checking out a specific release within the theme's directory. + +Switch to the theme's directory and list all available versions: + +``` +cd themes/<theme> +git tag +# exit with q +``` + +You can checkout a specific version as follows: + +``` +git checkout tags/<version-name> +``` + +You can update a theme to the latest version by executing the following command in the *root* directory of your project: + +``` +git submodule update --rebase --remote +``` + +## Next Steps + +You now have a live website served over https, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation: + +1. [Using a Custom Domain][] +2. [Setting up HTTPS on Custom Domains][httpscustom] +3. [Redirects and Rewrite Rules][] + + +[app.netlify.com]: https://app.netlify.com +[build command]: /getting-started/usage/#the-hugo-command +[config]: /getting-started/configuration/ +[ghsm]: https://github.com/blog/2104-working-with-submodules +[gitsm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[httpscustom]: https://www.netlify.com/docs/ssl/ +[hugoversions]: https://github.com/netlify/build-image/blob/master/Dockerfile#L216 +[installthemes]: /themes/installing/ +[netlify]: https://www.netlify.com/ +[netlifysignup]: https://app.netlify.com/signup +[Quick Start]: /getting-started/quick-start/ +[Redirects and Rewrite Rules]: https://www.netlify.com/docs/redirects/ +[Using a Custom Domain]: https://www.netlify.com/docs/custom-domains/ +[visit]: https://hugo-netlify-example.netlify.com diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-render.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-render.md new file mode 100644 index 0000000..bf719ea --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hosting-on-render.md @@ -0,0 +1,89 @@ +--- +title: Host on Render +linktitle: Host on Render +description: Host your Hugo site for free with Render's global CDN, fully-managed SSL and auto deploys from GitHub. +date: 2019-06-06 +publishdate: 2019-06-06 +lastmod: 2020-01-01 +categories: [hosting and deployment] +keywords: [render,hosting,deployment] +authors: [Anurag Goel] + +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +--- + +## Introduction + +[Render](https://render.com) is a fully-managed cloud platform where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. + +Static sites are **completely free** on Render and include the following: + +- Continuous, automatic builds & deploys from [GitHub](https://render.com/docs/github) and [GitLab](https://render.com/docs/gitlab). +- Automatic SSL certificates through [Let's Encrypt](https://letsencrypt.org). +- Instant cache invalidation with a lightning fast, global CDN. +- Unlimited collaborators. +- Unlimited [custom domains](https://render.com/docs/custom-domains). +- Automatic [Brotli compression](https://en.wikipedia.org/wiki/Brotli) for faster sites. +- Native HTTP/2 support. +- [Pull Request Previews](https://render.com/docs/pull-request-previews). +- Automatic HTTP → HTTPS redirects. +- Custom URL redirects and rewrites. + +## Assumptions + +* You have an account with GitHub or GitLab. +* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world. +* You have a Render account. You can sign up at https://render.com/register. + +## Deployment + +You can set up a Hugo site on Render in two quick steps: + +1. Create a new **Static Site** on Render, and give Render permission to access your GitHub/Gitlab repo. +2. Use the following values during creation: + + Field | Value + ------------------- | ------------------- + **Build Command** | `hugo --gc --minify` (or your own build command) + **Publish Directory** | `public` (or your own output directory) + +That's it! Your site will be live on your Render URL (which looks like `yoursite.onrender.com`) as soon as the build is done. + +## Continuous Deploys + +Now that Render is connected to your repo, it will **automatically build and publish your site** any time you push to your GitHub/Gitlab. + +You can choose to disable auto deploys under the **Settings** section for your site and deploy it manually from the Render dashboard. + +## CDN and Cache Invalidation + +Render hosts your site on a global, lightning fast CDN which ensures the fastest possible download times for all your users across the globe. + +Every deploy automatically and instantly invalidates the CDN cache, so your users can always access the latest content on your site. + +## Custom Domains + +Add your own domains to your site easily using Render's [custom domains](https://render.com/docs/custom-domains) guide. + +## Pull Request Previews + +With Pull Request (PR) previews, you can visualize changes introduced in a pull request instead of simply relying on code reviews. + +Once enabled, every PR for your site will automatically generate a new static site based on the code in the PR. It will have its own URL, and it will be deleted automatically when the PR is closed. + +Read more about [Pull Request Previews](https://render.com/docs/pull-request-previews) on Render. + +## Hugo Themes + +Render automatically downloads all Git submodules defined in your Git repo on every build. This way Hugo themes added as submodules work as expected. + +## Support + +Chat with Render developers at https://render.com/chat or email `support@render.com` if you need help. + + +[Quick Start]: /getting-started/quick-start/ diff --git a/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hugo-deploy.md b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hugo-deploy.md new file mode 100644 index 0000000..1d433d1 --- /dev/null +++ b/exampleSite/content/en/documentation/tutorials/hosting-and-deployment/hugo-deploy.md @@ -0,0 +1,131 @@ +--- +title: Hugo Deploy +linktitle: Hugo Deploy +description: You can upload your site to GCS, S3, or Azure using the Hugo CLI. +date: 2019-05-30 +publishdate: 2019-05-30 +lastmod: 2019-05-30 +categories: [hosting and deployment] +keywords: [s3,gcs,azure,hosting,deployment] +authors: [Robert van Gent] + +weight: 2 +sections_weight: 2 +draft: false +aliases: [] +toc: true +--- + +You can use the "hugo deploy" command to upload your site directly to a Google Cloud Storage (GCS) bucket, an AWS S3 bucket, and/or an Azure Storage container. + +## Assumptions + +* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world. +* You have an account with the service provider ([Google Cloud](https://cloud.google.com/), [AWS](https://aws.amazon.com), or [Azure](https://azure.microsoft.com)) that you want to deploy to. +* You have authenticated. + * Google Cloud: [Install the CLI](https://cloud.google.com/sdk) and run [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login). + * AWS: [Install the CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and run [`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). + * Azure: [Install the CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and run [`az login`](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). + * NOTE: Each service supports alternatives for authentication, including using environment variables. See [here](https://gocloud.dev/howto/blob/#services) for more details. + +## Create a bucket to deploy to + +Create a storage bucket to deploy your site to. If you want your site to be +public, be sure to configure the bucket to be publicly readable. + +### Google Cloud Storage (GCS) + +Follow the [GCS instructions for how to create a bucket](https://cloud.google.com/storage/docs/creating-buckets). + +### AWS S3 + +Follow the [AWS instructions for how to create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html). + +### Azure Storage + +Follow the [Azure instructions for how to create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal). + +## Configure the deployment + +In the configuration file for your site, add a `[deployment]` section with one +or more `[[deployment.targets]]` section, one for each deployment target. Here's +a detailed example: + +```toml +[deployment] +# By default, files are uploaded in an arbitrary order. +# Files that match the regular expressions in the "Order" list +# will be uploaded first, in the listed order. +order = [".jpg$", ".gif$"] + + +[[deployment.targets]] +# An arbitrary name for this target. +name = "mydeployment" +# The Go Cloud Development Kit URL to deploy to. Examples: +# GCS; see https://gocloud.dev/howto/blob/#gcs +# URL = "gs://<Bucket Name>" + +# S3; see https://gocloud.dev/howto/blob/#s3 +# For S3-compatible endpoints, see https://gocloud.dev/howto/blob/#s3-compatible +# URL = "s3://<Bucket Name>?region=<AWS region>" + +# Azure Blob Storage; see https://gocloud.dev/howto/blob/#azure +# URL = "azblob://$web" + +# You can use a "prefix=" query parameter to target a subfolder of the bucket: +# URL = "gs://<Bucket Name>?prefix=a/subfolder/" + +# If you are using a CloudFront CDN, deploy will invalidate the cache as needed. +cloudFrontDistributionID = <ID> + +# Optionally, you can include or exclude specific files. +# See https://godoc.org/github.com/gobwas/glob#Glob for the glob pattern syntax. +# If non-empty, the pattern is matched against the local path. +# All paths are matched against in their filepath.ToSlash form. +# If exclude is non-empty, and a local or remote file's path matches it, that file is not synced. +# If include is non-empty, and a local or remote file's path does not match it, that file is not synced. +# As a result, local files that don't pass the include/exclude filters are not uploaded to remote, +# and remote files that don't pass the include/exclude filters are not deleted. +# include = "**.html" # would only include files with ".html" suffix +# exclude = "**.{jpg, png}" # would exclude files with ".jpg" or ".png" suffix + + +# [[deployment.matchers]] configure behavior for files that match the Pattern. +# Samples: + +[[deployment.matchers]] +# Cache static assets for 1 year. +pattern = "^.+\\.(js|css|svg|ttf)$" +cacheControl = "max-age=31536000, no-transform, public" +gzip = true + +[[deployment.matchers]] +pattern = "^.+\\.(png|jpg)$" +cacheControl = "max-age=31536000, no-transform, public" +gzip = false + +[[deployment.matchers]] +pattern = "^.+\\.(html|xml|json)$" +gzip = true +``` + +## Deploy + +To deploy to a target: + +```bash +hugo deploy [--target=<target name>, defaults to first target] +``` + +Hugo will identify and apply any local changes that need to be reflected to the +remote target. You can use `--dryRun` to see the changes without applying them, +or `--confirm` to be prompted before making changes. + +See `hugo help deploy` for more command-line options. + +[Quick Start]: /getting-started/quick-start/ +[Google Cloud]: [https://cloud.google.com] +[AWS]: [https://aws.amazon.com] +[Azure]: [https://azure.microsoft.com] + diff --git a/exampleSite/content/en/tags/is_resource/_index.md b/exampleSite/content/en/tags/is_resource/_index.md new file mode 100644 index 0000000..d07c280 --- /dev/null +++ b/exampleSite/content/en/tags/is_resource/_index.md @@ -0,0 +1,3 @@ +--- +title: "Resource" +--- diff --git a/layouts/404.html b/layouts/404.html index 05d5248..0e0414c 100644 --- a/layouts/404.html +++ b/layouts/404.html @@ -1,10 +1,14 @@ {{ define "main" }} -<main class="clearfix p-5 lg:p-4 text-xl text-center mx-auto max-w-lg leading-normal text-gray-600"> - <h1 class="text-2xl sm:text-4xl">The page you're looking for doesn't exist. Perhaps you'd like to gopher something else? Sorry.</h1> - <div class="h6"> - <img src="/images/gopher-hero.svg" alt="" class="h-64"> - </div> + <main + class="clearfix p-5 lg:p-4 text-xl text-center mx-auto max-w-lg leading-normal text-gray-600"> + <h1 class="text-3xl sm:text-4xl"> + The page you're looking for doesn't exist. Perhaps you'd like to gopher + something else? Sorry. + </h1> + <div class="h6"> + <img src="/images/gopher-hero.svg" alt="" class="h-64" /> + </div> - {{ .Content }} -</main> + {{ .Content }} + </main> {{ end }} diff --git a/layouts/_default/list.html b/layouts/_default/list.html index 53ef574..4961813 100644 --- a/layouts/_default/list.html +++ b/layouts/_default/list.html @@ -1,20 +1,16 @@ {{ define "main" }} - {{ $pages := "" }} - {{ if .Parent.IsHome }} - {{/* /documentation root: Show all pages in the fundementals category. */}} - {{ $pages = (.Site.Taxonomies.categories.fundamentals).Pages | lang.Merge (.Sites.First.Taxonomies.categories.fundamentals).Pages }} - {{ else }} - {{ $pages = .Pages | union .Sections }} - {{ end }} + {{ $pages := .Pages }} <h1 class="text-3xl text-black font-semibold"> {{ .Title | title }} </h1> - <div class="mt-8 text-lg text-black"> - {{ .Content }} - </div> + {{ if gt (len .Content) 20 }} + <div class="mt-6 text-lg text-black"> + {{ .Content }} + </div> + {{ end }} {{ if $pages }} {{ $interior_classes := site.Params.flex_box_interior_classes }} - <section class="grid grid-cols-1 sm:grid-cols-2 gap-4 mt-8"> + <section class="grid grid-cols-1 sm:grid-cols-2 gap-4 mt-6"> {{ range $pages }} {{ partial "boxes-section-summaries.html" (dict "context" . "classes" $interior_classes "fullcontent" true) }} {{ end }} diff --git a/layouts/_default/page.html b/layouts/_default/page.html index 339df7d..09911b0 100644 --- a/layouts/_default/page.html +++ b/layouts/_default/page.html @@ -1,36 +1,43 @@ <header class="flex-none w-full"> {{ $categories := .GetTerms "categories" }} - {{ range $categories }} - <a - href="{{ .RelPermalink }}" - class="text-sm tracking-wider mb-0 link text-gray-500 dim mr-3"> - {{ .Title | upper }} - </a> - {{ end }} - + <div class="mb-2"> + {{ range $categories }} + <a + href="{{ .RelPermalink }}" + class="text-sm tracking-wider mb-0 link text-gray-500 dim mr-3"> + {{ .Title | upper }} + </a> + {{ end }} + </div> - <h1 class="text-4xl font-semibold leading-tight mb-3 my-0 pt-3 text-black"> + <h1 class="text-3xl font-semibold leading-tight mb-3 my-0 text-black"> {{ .Title }} </h1> </header> -{{/* TODO1 check usage */}} -{{ with .Params.featured_image_path }} - <img src="{{ . }}" alt="Featured Image for {{ $.Title }}" class="mw-100" /> -{{ end }} - - -<div class="mt-4 md:mt-8 prose lg:prose-lg" id="prose"> +<div class="mt-2 md:mt-4 prose lg:prose-lg" id="prose"> {{ with .Params.description }} - <div class="lead"> + <div class="text-base leading-relaxed mb-5"> {{ . | $.RenderString }} </div> {{ end }} - {{- partial "docs/functions-signature.html" . -}} - {{ .Content }} + {{ $tags := .GetTerms "tags" }} + {{ range $tags }} + {{ $color := partial "helpers/funcs/color-from-string" .LinkTitle }} + {{ $class := printf "text-%s-600 bg-%s-200" $color $color }} + <a + href="{{ .RelPermalink }}" + class="{{ $class }} text-xs font-semibold no-underline inline-block py-1 px-2 uppercase rounded-full uppercase last:mr-0 mr-1 hover:opacity-75"> + {{ .LinkTitle | upper }} + </a> + {{ end }} + <div class="mt-4"> + {{ .Content }} + </div> + <hr /> {{ with .File }} <div class="mt-8"> @@ -43,14 +50,20 @@ </div> {{ end }} - - <div class="mt-4 text-gray-300 text-sm"> - Last updated: - {{ .Lastmod.Format "January 2, 2006" }}{{ with .GitInfo }} - : - <a href="{{ site.Params.ghrepo }}commit/{{ .Hash }}" - >{{ .Subject }} ({{ .AbbreviatedHash }})</a - > - {{ end }} - </div> + {{ if .Lastmod }} + <div class="mt-4 text-gray-300 text-sm"> + Last updated: + {{ .Lastmod.Format "January 2, 2006" }}{{ with .GitInfo }} + : + <a href="{{ site.Params.ghrepo }}commit/{{ .Hash }}" + >{{ .Subject }} ({{ .AbbreviatedHash }})</a + > + {{ end }} + </div> + {{ end }} </div> + +{{ define "toc" }} + {{ $tocPartial := "" }} + {{- partial "toc.html" (dict "p" . "partial" $tocPartial ) -}} +{{ end }} diff --git a/layouts/documentation/baseof.html b/layouts/documentation/baseof.html index fe77cab..86083c6 100644 --- a/layouts/documentation/baseof.html +++ b/layouts/documentation/baseof.html @@ -1,15 +1,18 @@ <!DOCTYPE html> <html id="gohugoio" class="no-js nightwind" lang="{{ .Site.Language.Lang }}"> {{ partial "sections/common/head.html" . }} - <body class="m-0 font-sans"> + <body class="{{ .Section }} m-0 font-sans bg-gray-50"> {{ partial "sections/common/after-body-start.html" . }} - <div class="bg-white"> + <div class=""> {{ block "nav" . }} {{ partial "sections/nav/menu.html" . }} {{ end }} {{ block "header" . }}{{ end }} <main role="main" class="min-h-screen container mx-auto pb-7 sm:pb-0"> - <div class="h-screen flex overflow-hidden" x-data="{ open: false }"> + {{ partial "sections/nav/icons.html" . }} + <div + class="h-screen flex overflow-hidden" + x-data__="{ TODO1 open: false }"> {{/* Mobile menu */}} <div class="fixed inset-0 flex z-40 lg:hidden" @@ -47,7 +50,7 @@ <div class="flex-1 h-0 pt-5 pb-4 overflow-y-auto"> <nav aria-label="Sidebar" class="mt-5"> <div class="px-4 space-y-1"> - {{ partial "sections/nav/docs-explorer.html" . }} + {{/* partial "sections/nav/docs-explorer.html" . */}} </div> </nav> </div> @@ -60,9 +63,14 @@ <div class="hidden lg:flex lg:flex-shrink-0"> <div class="flex flex-col w-64"> <div class="flex flex-col h-0 flex-1 border-r border-gray-200"> - <div class="flex-1 flex flex-col pt-5 pb-4 overflow-y-auto"> + <div + class="flex-1 flex flex-col pt-5 pb-4 overflow-y-auto" + data-turbo-preserve-scroll-container="sidebar"> <nav class="mt-0 flex-1" aria-label="Sidebar"> <div class="px-0"> + <div class="mt-2 mb-4 pr-6"> + {{ partial "sections/nav/fake-searchinput.html" . }} + </div> {{ partial "sections/nav/docs-explorer.html" . }} </div> </nav> @@ -106,24 +114,27 @@ </div> <div class="flex-1 relative z-0 flex overflow-hidden pb-8 md:pb-12"> <main - class="flex-1 relative z-0 overflow-y-auto focus:outline-none" + class="flex-1 relative z-0 overflow-y-auto focus:outline-none bg-white" tabindex="0"> {{/* Main */}} - <div class="absolute inset-0 py-6 sm:py-8 px-4 sm:px-6 lg:px-8"> + <div class="py-6 sm:py-8 px-4 sm:px-6 lg:px-8"> + <div> + {{ partial "sections/nav/breadcrumbs.html" . }} + </div> <div - class="h-full border-2 border-gray-200 border-none rounded-lg"> + class="h-full border-2 border-gray-200 border-none mt-4 rounded-lg"> {{ block "main" . }}{{ end }} </div> </div> </main> {{ if .IsPage }} <aside - class="hidden relative xl:flex xl:flex-col flex-shrink-0 w-96 border-l border-gray-200 overflow-auto"> + class="hidden relative xl:flex xl:flex-col flex-shrink-0 w-96 border-l border-gray-200 overflow-auto bg-white"> {{/* Secondary col */}} - <div class="absolute inset-0 py-6 px-4 sm:px-6 lg:px-8"> + <div class="px-4 sm:px-6 lg:px-8"> <div - class="h-full border-2 border-gray-200 border-none rounded-lg"> - {{- partial "toc.html" . -}} + class="h-full border-2 border-gray-200 border-none rounded-lg mt-2 lg:mt-8"> + {{ block "toc" . }}{{ end }} </div> </div> </aside> diff --git a/layouts/index.doctree.json b/layouts/index.doctree.json new file mode 100644 index 0000000..9ead470 --- /dev/null +++ b/layouts/index.doctree.json @@ -0,0 +1,13 @@ +{{ $root := site.GetPage "documentation" }} +{{ $tree := (dict "title" $root.LinkTitle "href" $root.RelPermalink "children" (partial "navigation-get-children-recursive" $root ) ) }} + +{{ $tree | jsonify}} + +{{ define "partials/navigation-get-children-recursive" }} + {{ $pages := $.Sections }} + {{ $children := slice }} + {{ range $pages}} + {{ $children = $children | append (dict "title" .LinkTitle "href" .RelPermalink "children" (partial "navigation-get-children-recursive" . ) ) }} + {{ end }} + {{ return $children}} +{{ end }}
\ No newline at end of file diff --git a/layouts/news/list.html b/layouts/news/list.html index 6714f90..987a332 100644 --- a/layouts/news/list.html +++ b/layouts/news/list.html @@ -24,7 +24,7 @@ {{ $interior_classes := $.Site.Params.flex_box_interior_classes }} <section class="sm:flex flex-wrap justify-between w-full w-80-nsTK v-top"> - {{ $paginator := .Paginate (.Pages | lang.Merge (where .Sites.First.RegularPages "Section" .Section)) -}} + {{ $paginator := .Paginator -}} {{ range $paginator.Pages }} {{ partial "boxes-section-summaries" (dict "context" . "classes" $interior_classes "fullcontent" false) }} {{ end }} diff --git a/layouts/news/single.html b/layouts/news/single.html index 7724361..27ddf47 100644 --- a/layouts/news/single.html +++ b/layouts/news/single.html @@ -7,7 +7,7 @@ {{ range .Params.categories }} <a href="{{ "/categories/" | relLangURL }}{{ . | urlize }}" - class="text-sm font-extrabold mb-0 link text-gray-500 dim mr-3"> + class="text-sm font-semibold mb-0 link text-gray-500 dim mr-3"> {{ humanize . | upper }} </a> {{ end }} diff --git a/layouts/partials/boxes-section-summaries.html b/layouts/partials/boxes-section-summaries.html index 7c4e6e6..fcc52f8 100644 --- a/layouts/partials/boxes-section-summaries.html +++ b/layouts/partials/boxes-section-summaries.html @@ -1,11 +1,15 @@ -<div class="relative bg-white border border-gray-100 mb-2 p-3 lg:p-4 text-gray-600"> +<div + class="relative bg-white border border-gray-100 shadow-sm mb-2 p-3 lg:p-4 text-gray-600"> {{ if eq .context.Section "news" }} - <date class="text-sm block" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}"> + <date + class="text-sm block" + datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" }}"> {{ .context.Date.Format "January 2, 2006" }} </date> {{ end }} - - <h2 class="text-gray-900 text-2xl"> + + + <h2 class="text-gray-900 text-xl"> <a href="{{ .context.RelPermalink }}" class="link text-steel-500 dim"> {{- if eq .context.Section "functions" -}} {{ .context.LinkTitle }} @@ -14,15 +18,18 @@ {{- end -}} </a> </h2> - - <div class="leading-normal tracking-normal mt-2"> - {{ if .context.Params.description }} + + <div class="leading-snug tracking-normal mt-2"> + {{ if .context.Params.description }} {{ .context.Params.description | markdownify }} {{ else }} - {{ .context.Summary }} + {{ .context.Summary }} {{ end }} - - <a href="{{ .context.RelPermalink }}" class="text-sm mt-2 block link text-steel-500 dim"> + + + <a + href="{{ .context.RelPermalink }}" + class="text-sm mt-2 block link text-steel-500 dim"> Read More » </a> </div> diff --git a/layouts/partials/docs/functions-signature.html b/layouts/partials/documentation/functions-signature.html index 04a7480..04a7480 100644 --- a/layouts/partials/docs/functions-signature.html +++ b/layouts/partials/documentation/functions-signature.html diff --git a/layouts/partials/documentation/reference/list-namespace.html b/layouts/partials/documentation/reference/list-namespace.html new file mode 100644 index 0000000..aa90ccc --- /dev/null +++ b/layouts/partials/documentation/reference/list-namespace.html @@ -0,0 +1,61 @@ +{{ $namespace := .Params.namespace }} +{{ $all := index site.Data.docs.tpl "funcs" }} +{{ $funcs := index $all $namespace }} + +{{ range $k, $v := $funcs }} + {{ $m := partial "format-func-godoc" (dict "ns" $namespace "k" $k "v" $v) }} + <h2 id="{{ $k | anchorize }}" class="border-b"> + {{ $namespace }}.{{ $k }} + </h2> + {{ with $.Resources.GetMatch (printf "explanation/%s.md" ($k | lower) ) }} + {{ .Content }} + {{ else }} + <p> + {{ $.RenderString $m.desc }} + </p> + {{ end }} + {{ with $v.Args }} + <p + class="mt-8 font-mono font-semibold text-sm border-steel-700 p-2 bg-green-50 border-l-4 border-green-100 border-opacity-50"> + {{ $namespace }}.{{ $k }} + {{ delimit (apply . "upper" ".") " " }} + </p> + {{ end }} + + {{ with $v.Aliases }} + <p class="w-30 bg-steel-50 border p-2"> + <b>Aliases:</b> <span class="font-mono">{{ delimit . ", " }}</span> + </p> + {{ end }} + + {{ if $v.Examples }} + <h3>Examples</h3> + {{ end }} + + {{ range $v.Examples }} + {{ $in := index . 0 }} + {{ $out := index . 1 }} + <div class="flex flex-wrap overflow-auto"> + <div class="w-full md:w-1/2"> + {{ transform.Highlight $in "go-html-template" "" }} + </div> + <div class="w-full md:w-1/2 md:pl-2"> + {{ transform.Highlight $out "go-html-template" "" }} + </div> + </div> + {{ end }} +{{ end }} + +{{ define "partials/format-func-godoc" }} + {{ $m := newScratch }} + {{ $k := .k }} + {{ $ns := .ns }} + {{ $description := .v.Description }} + {{ range .v.Args }} + {{ $description = replace $description . (printf "`%s`" ( . | upper ) ) }} + {{ end }} + {{ $description = replace $description $k (printf "`%s`" $k ) }} + {{ $description := replaceRE "{{(.*?) }}" "`{{ $1 }}`" $description }} + {{ $m.Set "desc" $description }} + {{ return $m.Values }} +{{ end }} diff --git a/layouts/partials/documentation/reference/namespace-toc.html b/layouts/partials/documentation/reference/namespace-toc.html new file mode 100644 index 0000000..1557fcc --- /dev/null +++ b/layouts/partials/documentation/reference/namespace-toc.html @@ -0,0 +1,16 @@ +{{ $namespace := .Params.namespace }} +{{ $all := index site.Data.docs.tpl "funcs" }} +{{ $funcs := index $all $namespace }} + + +<h3 class="text-lg font-bold">What's on this Page</h3> +<div class="leading-relaxed tracking-tight mt-2 mb-8"> + <nav id="TableOfContents"> + <ul> + {{ range $k, $v := $funcs }} + {{ $id := $k | anchorize }} + <li><a href="#{{ $id }}">{{ $k }}</a></li> + {{ end }} + </ul> + </nav> +</div> diff --git a/layouts/partials/helpers/docs/get-func.html b/layouts/partials/helpers/docs/get-func.html new file mode 100644 index 0000000..ea1eb59 --- /dev/null +++ b/layouts/partials/helpers/docs/get-func.html @@ -0,0 +1,9 @@ +{{ $all := index site.Data.docs.tpl "funcs" }} +{{ $parts := split . "." }} +{{ $func := "" }} +{{ if eq (len $parts) 2 }} + {{ $funcs := index $all (index $parts 0) }} + {{ $func = index $funcs (index $parts 1) }} +{{ end }} + +{{ return $func }} diff --git a/layouts/partials/helpers/funcs/color-from-string.html b/layouts/partials/helpers/funcs/color-from-string.html new file mode 100644 index 0000000..5060812 --- /dev/null +++ b/layouts/partials/helpers/funcs/color-from-string.html @@ -0,0 +1,5 @@ +{{ $colors := slice "orange" "blue" "green" "steel" "hotpink" }} +{{ $hash := (crypto.FNV32a .) }} +{{ $i := mod $hash (len $colors) }} +{{ $color := index $colors $i }} +{{ return $color }} diff --git a/layouts/partials/home-page-sections/features-icons.html b/layouts/partials/home-page-sections/features-icons.html index a63d205..86c631a 100644 --- a/layouts/partials/home-page-sections/features-icons.html +++ b/layouts/partials/home-page-sections/features-icons.html @@ -23,7 +23,7 @@ <div class="flex-auto text-center sm:text-left w-full sm:w-4/5"> <h3 - class="leading-tight text-gray-600 o-80 text-xl sm:text-base mb-2 font-extrabold bmt1 lg:mt-0"> + class="leading-tight text-gray-600 o-80 text-xl sm:text-base mb-2 font-semibold bmt1 lg:mt-0"> {{ .heading }} </h3> <div diff --git a/layouts/partials/sections/common/head.html b/layouts/partials/sections/common/head.html index b281658..1db07f2 100644 --- a/layouts/partials/sections/common/head.html +++ b/layouts/partials/sections/common/head.html @@ -9,13 +9,14 @@ {{/* TODO1 self host https://fonts.google.com/specimen/Mulish?preview.text_type=custom */}} <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin /> <link - href="https://fonts.googleapis.com/css2?family=Mulish:ital,wght@0,300;0,400;0,700;1,400;1,700&display=swap" + href="https://fonts.googleapis.com/css2?family=Mulish:ital,wght@0,300;0,500;0,700;1,500;1,700&display=swap" rel="stylesheet" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> {{/* NOTE: the Site's title, and if there is a page title, that is set too */}} <title> {{ block "title" . }} - {{ with .Title }}{{ . }} |{{ end }}{{ .Site.Title }} + {{ with .Title }}{{ . }} |{{ end }} + {{ .Site.Title }} {{ end }} </title> @@ -55,6 +56,10 @@ crossorigin="anonymous" /> {{ end }} + {{/* TODO1 remove */}} + <link + rel="stylesheet" + href="https://cdnjs.cloudflare.com/ajax/libs/MaterialDesign-Webfont/5.3.45/css/materialdesignicons.min.css" /> <style> [x-cloak] { diff --git a/layouts/partials/sections/nav/breadcrumbs.html b/layouts/partials/sections/nav/breadcrumbs.html new file mode 100644 index 0000000..095d885 --- /dev/null +++ b/layouts/partials/sections/nav/breadcrumbs.html @@ -0,0 +1,37 @@ +{{ $root := site.GetPage "documentation" }} +{{ $p := . }} + + +<nav class="flex" aria-label="Breadcrumb"> + <ol + class="inline-flex items-center -mx-1 space-x-2 flex-wrap tracking-tighter"> + {{ template "breadcrums-item" (dict "root" $root "p1" $p "p2" $p ) }} + </ol> +</nav> + +{{ define "breadcrums-item" }} + {{ if and .p1.Parent (ne .p1.Parent .root.Parent) }} + {{ template "breadcrums-item" (dict "root" .root "p1" .p1.Parent "p2" .p2 ) }} + {{ end }} + {{ if and .p1.Parent .p1.Parent.IsHome (or (eq .p1.Kind "term") (eq .p1.Kind "taxonomy")) }} + {{ template "breadcrums-item" (dict "root" .root "p1" .root "p2" .p2 ) }} + {{ end }} + <li> + <div class="flex items-center"> + {{ if or .p1.IsNode (ne .p1 .p2) }} + {{ if ne .p1 .root }} + {{ template "breadcrumbs-arrow" . }} + {{ end }} + <a href="{{ .p1.Permalink }}" class="truncate ml-1"> + {{ .p1.LinkTitle | title }} + </a> + {{ end }} + </div> + </li> +{{ end }} + +{{ define "breadcrumbs-arrow" }} + <svg class="text-gray-400 w-5 h-5 mr-2"> + <use href="#icon--chevron-right"></use> + </svg> +{{ end }} diff --git a/layouts/partials/sections/nav/docs-explorer copy.html b/layouts/partials/sections/nav/docs-explorer copy.html new file mode 100644 index 0000000..c6d66a4 --- /dev/null +++ b/layouts/partials/sections/nav/docs-explorer copy.html @@ -0,0 +1,57 @@ +{{ $currentPage := . }} +<nav + role="navigation" + id="main-menu" + x-data="{ menu: {}, show: true }" + data-turbolinks-permanent> + <ul x-cloak class="p-0" x-show.transition.in.opacity.300ms="show"> + {{ range .Site.Menus.docs.ByWeight }} + {{ $post := printf "%s" .Post }} + <li + class="text-base w-full hover:text-hotpink-400 font-semibold{{ if eq $post "break" }} + pb-1 border-b border-solid border-gray-200 dark:border-gray-800 + {{ end }}"> + {{ $isCurrent := or ($currentPage.IsMenuCurrent "docs" .) ($currentPage.HasMenuCurrent "docs" .) }} + {{ if .HasChildren }} + <a + @click="menu['{{ .Identifier }}'] = ('{{ .Identifier }}' in menu) ? !menu['{{ .Identifier }}'] : !{{ $isCurrent }}" + class="pl-3 inline-block w-full link text-gray-500 cursor-pointer hover:text-hotpink-400 pr-2 py-2 {{ if $isCurrent }} + text-steel-500 + {{ end }}"> + {{ .Name }} + </a> + {{ else }} + <a + href="{{ .URL }}" + class="pl-3 inline-block w-full link text-gray-500 hover:text-hotpink-400 pr-2 py-1 {{ if $isCurrent }} + text-steel-500 + {{ end }}" + data-target=".{{ .Identifier }}"> + {{ .Name }} + </a> + {{ end }} + + {{- if .HasChildren }} + {{ $hasCurrent := $currentPage.IsMenuCurrent "docs" . }} + <ul + class="pl-0" + x-show.transition.origin.top.left="({{ $isCurrent }} && !('{{ .Identifier }}' in menu)) || menu['{{ .Identifier }}']"> + {{- range .Children }} + <li class="text-sm font-normal"> + <a + href="{{ .URL }}" + class="block hover:bg-gray-50 hover:text-hotpink-600 pl-6 pr-2 pb-1.5 {{ if $hasCurrent }} + text-steel-500 + {{ else }} + black + {{ end }}"> + {{ .Name }} + </a> + </li> + {{- end }} + </ul> + {{- end }} + </li> + {{- end }} + </ul> +</nav> diff --git a/layouts/partials/sections/nav/docs-explorer.html b/layouts/partials/sections/nav/docs-explorer.html index 7a4c357..f6884b8 100644 --- a/layouts/partials/sections/nav/docs-explorer.html +++ b/layouts/partials/sections/nav/docs-explorer.html @@ -1,57 +1,54 @@ -{{ $currentPage := . }} <nav role="navigation" id="main-menu" - x-data="{ menu: {}, show: true }" - data-turbolinks-permanent> - <ul x-cloak class="p-0" x-show.transition.in.opacity.300ms="show"> - {{ range .Site.Menus.docs.ByWeight }} - {{ $post := printf "%s" .Post }} - <li - class="text-base w-full hover:text-hotpink-400 font-extrabold{{ if eq $post "break" }} - pb-1 border-b border-solid border-gray-200 dark:border-gray-800 - {{ end }}"> - {{ $isCurrent := or ($currentPage.IsMenuCurrent "docs" .) ($currentPage.HasMenuCurrent "docs" .) }} - {{ if .HasChildren }} - <a - @click="menu['{{ .Identifier }}'] = ('{{ .Identifier }}' in menu) ? !menu['{{ .Identifier }}'] : !{{ $isCurrent }}" - class="pl-3 inline-block w-full link text-gray-500 cursor-pointer hover:text-hotpink-400 pr-2 py-2 {{ if $isCurrent }} - text-steel-500 - {{ end }}"> - {{ .Name }} - </a> - {{ else }} - <a - href="{{ .URL }}" - class="pl-3 inline-block w-full link text-gray-500 hover:text-hotpink-400 pr-2 py-1 {{ if $isCurrent }} - text-steel-500 - {{ end }}" - data-target=".{{ .Identifier }}"> - {{ .Name }} - </a> - {{ end }} - - {{- if .HasChildren }} - {{ $hasCurrent := $currentPage.IsMenuCurrent "docs" . }} - <ul - class="pl-0" - x-show.transition.origin.top.left="({{ $isCurrent }} && !('{{ .Identifier }}' in menu)) || menu['{{ .Identifier }}']"> - {{- range .Children }} - <li class="text-sm font-normal"> - <a - href="{{ .URL }}" - class="block hover:bg-gray-50 hover:text-hotpink-600 pl-6 pr-2 pb-1.5 {{ if $hasCurrent }} - text-steel-500 - {{ else }} - black - {{ end }}"> - {{ .Name }} - </a> - </li> - {{- end }} - </ul> - {{- end }} - </li> - {{- end }} + class="mt-1 md:mt-2 mx-2 w-4/5 overflow-auto bg-gray-50 p-2" + x-data="docTreeController()" + data-turbo-permanent + @turbo:before-render.window="onBeforeRender()" + x-cloak> + <ul class="p-0 border-l border-gray-200"> + {{ $root := site.GetPage "documentation" }} + {{ template "docs-explorer-section" (dict "p" $root "level" 1 ) }} </ul> </nav> + +{{ define "docs-explorer-section" }} + {{ $p := .p }} + {{ $level := .level }} + {{ $pleft := add .level 1 }} + + {{ $pl := printf "pl-%d" $pleft }} + {{ $plCurrent := printf "pl-%d" (sub $pleft 2 ) }} + {{ $pages := ($p.Pages | union $p.Sections).ByWeight }} + {{ $pages = where $pages "Weight" "lt" 1000 }} + + {{ range $pages }} + {{ $hasChildren := gt (len .Pages) 0 }} + {{ $class := cond (eq $level 1) "text-black hover:text-gray-900" "text-gray-600 hover:text-gray-500" }} + <li class="w-full"> + {{ if $hasChildren }} + <a + @click.prevent="toggleNode('{{ .RelPermalink }}')" + :class="{ 'font-semibold border-l-2': isCurrent('{{ .RelPermalink }}') }" + class="block cursor-pointer {{ $pl }} {{ $class }} tracking-tight leading-7 hover:bg-gray-100"> + <span :class="{ 'pl-2px': !isCurrent('{{ .RelPermalink }}') }" + >{{ .LinkTitle }}</span + > + </a> + <ul class="" x-show="isOpen('{{ .RelPermalink }}')"> + {{ template "docs-explorer-section" (dict "p" . "level" (add $level 1)) }} + </ul> + {{ else }} + <a + class="block box-content cursor-pointer {{ $pl }} text-gray-700 hover:text-gray-600 tracking-tight leading-7 hover:bg-gray-100" + :class="{ 'font-semibold border-l-2': isCurrent('{{ .RelPermalink }}') }" + href="{{ .RelPermalink }}" + ><span :class="{ 'pl-2px': !isCurrent('{{ .RelPermalink }}') }" + >{{ .LinkTitle }}</span + ></a + > + {{ end }} + </li> + {{ end }} + +{{ end }} diff --git a/layouts/partials/sections/nav/fake-searchinput.html b/layouts/partials/sections/nav/fake-searchinput.html new file mode 100644 index 0000000..80d0ee0 --- /dev/null +++ b/layouts/partials/sections/nav/fake-searchinput.html @@ -0,0 +1,30 @@ +<div class="bg-white relative" x-data> + <button + @click="$dispatch('open-search')" + type="button" + class="hidden w-full lg:flex text-gray-600 dark:text-gray-400 items-center text-sm leading-6 border border-gray-100 shadow-sm py-1 pl-2 pr-3"> + <svg + width="24" + height="24" + fill="none" + aria-hidden="true" + class="mr-3 flex-none"> + <path + d="m19 19-3.5-3.5" + stroke="currentColor" + stroke-width="2" + stroke-linecap="round" + stroke-linejoin="round"></path> + <circle + cx="11" + cy="11" + r="6" + stroke="currentColor" + stroke-width="2" + stroke-linecap="round" + stroke-linejoin="round"></circle></svg + >Search the Docs<span class="ml-auto pl-3 flex-none text-xs font-semibold" + >⌘K</span + > + </button> +</div> diff --git a/layouts/partials/sections/nav/icons.html b/layouts/partials/sections/nav/icons.html new file mode 100644 index 0000000..78181a8 --- /dev/null +++ b/layouts/partials/sections/nav/icons.html @@ -0,0 +1,8 @@ +<svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> + <symbol id="icon--chevron-right" viewBox="0 0 20 20"> + <path + fill-rule="evenodd" + d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z" + clip-rule="evenodd"></path> + </symbol> +</svg> diff --git a/layouts/partials/sections/nav/menu.html b/layouts/partials/sections/nav/menu.html index aa1d739..d3d9766 100644 --- a/layouts/partials/sections/nav/menu.html +++ b/layouts/partials/sections/nav/menu.html @@ -1,5 +1,5 @@ <nav - class="nightwind-prevent bg-gray-900 flex flex-wrap items-center justify-between p-4 m-0 z-20" + class="nightwind-prevent bg-gray-900 flex flex-wrap items-center justify-between p-2 m-0 z-20" x-data="{ open: false }"> <div class="container mx-auto flex flex-shrink-0 items-center"> <div class="mr-10"> diff --git a/layouts/partials/sections/nav/search.html b/layouts/partials/sections/nav/search.html index fe47ff6..230beb2 100644 --- a/layouts/partials/sections/nav/search.html +++ b/layouts/partials/sections/nav/search.html @@ -2,6 +2,8 @@ <div> <button @click="toggleOpen()" + @open-search.window="toggleOpen()" + @keydown.meta.k.window="toggleOpen()" class="nightwind-prevent inline-flex items-center p-2 border border-transparent rounded-full shadow-sm text-black bg-blue-400 hover:bg-blue-600 hover:text-gray-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-steel-500"> <svg xmlns="http://www.w3.org/2000/svg" diff --git a/layouts/partials/toc.html b/layouts/partials/toc.html index 72c14a8..80fba2c 100644 --- a/layouts/partials/toc.html +++ b/layouts/partials/toc.html @@ -1,18 +1,23 @@ -<!-- TOCs need to be declared explicitly in the front matter of content/*.md --> +{{ $p := .p }} +{{ $tocPartial := .partial }} <aside - class="fixed-lTK mw5-l right-0 text-sm py-4 sm:py-0 lg:px-4 nested-list-reset nested-links leading-normal text-black"> - {{ if .Params.toc }} - {{ with .TableOfContents }} - {{ if ge (len .) 100 }} - <h3 class="text-lg font-bold">What's on this Page</h3> - <div class="leading-relaxed tracking-tight mt-2 mb-8"> - {{ . }} - </div> + class="right-0 text-sm lg:px-4 nested-list-reset nested-links leading-normal text-black"> + {{ with $tocPartial }} + {{ partial $tocPartial $p }} + {{ else }} + {{ if not $p.Params.notoc }} + {{ with $p.TableOfContents }} + {{ if ge (len .) 100 }} + <h3 class="text-lg font-bold">What's on this Page</h3> + <div class="leading-relaxed tracking-tight mt-2 mb-8"> + {{ . }} + </div> + {{ end }} {{ end }} {{ end }} {{ end }} - {{ $related := .Site.RegularPages.Related . | first 5 }} + {{ $related := site.RegularPages.Related $p | first 5 }} {{ with $related }} <h3 class="text-lg font-bold">See Also</h3> <ul class="text-md mt-2"> diff --git a/layouts/shortcodes/docs/func-aliases.html b/layouts/shortcodes/docs/func-aliases.html new file mode 100644 index 0000000..1485704 --- /dev/null +++ b/layouts/shortcodes/docs/func-aliases.html @@ -0,0 +1,8 @@ +{{ $func := (partial "helpers/docs/get-func.html" (.Get 0)) }} +{{ with $func }} + {{ with .Aliases }} + <p class="border border-gray-200 mt-4 p-2 w-3/4"> + <b>Aliases:</b> <span class="font-mono">{{ delimit . ", " }}</span> + </p> + {{ end }} +{{ end }} diff --git a/layouts/shortcodes/docs/func-examples.html b/layouts/shortcodes/docs/func-examples.html new file mode 100644 index 0000000..9df9c35 --- /dev/null +++ b/layouts/shortcodes/docs/func-examples.html @@ -0,0 +1,18 @@ +{{ $func := (partial "helpers/docs/get-func.html" (.Get 0)) }} +{{ with $func }} + {{ with .Examples }} + <h3>Examples</h3> + {{ range . }} + {{ $in := index . 0 }} + {{ $out := index . 1 }} + <div class="flex flex-wrap overflow-auto"> + <div class="w-full md:w-1/2"> + {{ transform.Highlight $in "go-html-template" "" }} + </div> + <div class="w-full md:w-1/2 md:pl-2"> + {{ transform.Highlight $out "go-html-template" "" }} + </div> + </div> + {{ end }} + {{ end }} +{{ end }} diff --git a/netlify.toml b/netlify.toml index acac0b7..225eb0a 100644 --- a/netlify.toml +++ b/netlify.toml @@ -4,18 +4,18 @@ command = "hugo --gc --minify" ignore = "/bin/false" [context.production.environment] -HUGO_VERSION = "0.93.1" +HUGO_VERSION = "0.98.0" [context.deploy-preview] command = "hugo --minify -D -F -b $DEPLOY_PRIME_URL" [context.deploy-preview.environment] -HUGO_VERSION = "0.93.1" +HUGO_VERSION = "0.98.0" [context.branch-deploy] command = "hugo --minify --gc -b $DEPLOY_PRIME_URL" [context.branch-deploy.environment] -HUGO_VERSION = "0.93.1" +HUGO_VERSION = "0.98.0" diff --git a/static/android-chrome-144x144.png b/static/android-chrome-144x144.png Binary files differnew file mode 100644 index 0000000..975cb33 --- /dev/null +++ b/static/android-chrome-144x144.png diff --git a/static/android-chrome-192x192.png b/static/android-chrome-192x192.png Binary files differnew file mode 100644 index 0000000..7ab6c38 --- /dev/null +++ b/static/android-chrome-192x192.png diff --git a/static/android-chrome-256x256.png b/static/android-chrome-256x256.png Binary files differnew file mode 100644 index 0000000..ed88a22 --- /dev/null +++ b/static/android-chrome-256x256.png diff --git a/static/android-chrome-36x36.png b/static/android-chrome-36x36.png Binary files differnew file mode 100644 index 0000000..3695eb0 --- /dev/null +++ b/static/android-chrome-36x36.png diff --git a/static/android-chrome-48x48.png b/static/android-chrome-48x48.png Binary files differnew file mode 100644 index 0000000..ca275da --- /dev/null +++ b/static/android-chrome-48x48.png diff --git a/static/android-chrome-72x72.png b/static/android-chrome-72x72.png Binary files differnew file mode 100644 index 0000000..966891f --- /dev/null +++ b/static/android-chrome-72x72.png diff --git a/static/android-chrome-96x96.png b/static/android-chrome-96x96.png Binary files differnew file mode 100644 index 0000000..feb1d3e --- /dev/null +++ b/static/android-chrome-96x96.png diff --git a/static/browserconfig.xml b/static/browserconfig.xml new file mode 100644 index 0000000..62400c5 --- /dev/null +++ b/static/browserconfig.xml @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="utf-8"?> +<browserconfig> + <msapplication> + <tile> + <square150x150logo src="images/favicons/mstile-150x150.png"/> + <square310x310logo src="images/favicons/mstile-310x310.png"/> + <TileColor>#2d89ef</TileColor> + </tile> + </msapplication> +</browserconfig> diff --git a/static/favicon-16x16.png b/static/favicon-16x16.png Binary files differnew file mode 100644 index 0000000..c62ce6f --- /dev/null +++ b/static/favicon-16x16.png diff --git a/static/favicon-32x32.png b/static/favicon-32x32.png Binary files differnew file mode 100644 index 0000000..57a018e --- /dev/null +++ b/static/favicon-32x32.png diff --git a/static/favicon.ico b/static/favicon.ico Binary files differnew file mode 100644 index 0000000..dc007a9 --- /dev/null +++ b/static/favicon.ico diff --git a/static/fonts/mulish-v10-latin-200.woff b/static/fonts/mulish-v10-latin-200.woff Binary files differnew file mode 100644 index 0000000..00f3a71 --- /dev/null +++ b/static/fonts/mulish-v10-latin-200.woff diff --git a/static/fonts/mulish-v10-latin-200.woff2 b/static/fonts/mulish-v10-latin-200.woff2 Binary files differnew file mode 100644 index 0000000..dd830d8 --- /dev/null +++ b/static/fonts/mulish-v10-latin-200.woff2 diff --git a/static/fonts/mulish-v10-latin-800.woff b/static/fonts/mulish-v10-latin-800.woff Binary files differnew file mode 100644 index 0000000..31425db --- /dev/null +++ b/static/fonts/mulish-v10-latin-800.woff diff --git a/static/fonts/mulish-v10-latin-800.woff2 b/static/fonts/mulish-v10-latin-800.woff2 Binary files differnew file mode 100644 index 0000000..4066d6a --- /dev/null +++ b/static/fonts/mulish-v10-latin-800.woff2 diff --git a/static/fonts/mulish-v10-latin-800italic.woff b/static/fonts/mulish-v10-latin-800italic.woff Binary files differnew file mode 100644 index 0000000..d721ae7 --- /dev/null +++ b/static/fonts/mulish-v10-latin-800italic.woff diff --git a/static/fonts/mulish-v10-latin-800italic.woff2 b/static/fonts/mulish-v10-latin-800italic.woff2 Binary files differnew file mode 100644 index 0000000..bef9c6e --- /dev/null +++ b/static/fonts/mulish-v10-latin-800italic.woff2 diff --git a/static/fonts/mulish-v10-latin-italic.woff b/static/fonts/mulish-v10-latin-italic.woff Binary files differnew file mode 100644 index 0000000..d604ca3 --- /dev/null +++ b/static/fonts/mulish-v10-latin-italic.woff diff --git a/static/fonts/mulish-v10-latin-italic.woff2 b/static/fonts/mulish-v10-latin-italic.woff2 Binary files differnew file mode 100644 index 0000000..ef9b1fd --- /dev/null +++ b/static/fonts/mulish-v10-latin-italic.woff2 diff --git a/static/fonts/mulish-v10-latin-regular.woff b/static/fonts/mulish-v10-latin-regular.woff Binary files differnew file mode 100644 index 0000000..93fca94 --- /dev/null +++ b/static/fonts/mulish-v10-latin-regular.woff diff --git a/static/fonts/mulish-v10-latin-regular.woff2 b/static/fonts/mulish-v10-latin-regular.woff2 Binary files differnew file mode 100644 index 0000000..93e2b44 --- /dev/null +++ b/static/fonts/mulish-v10-latin-regular.woff2 diff --git a/static/mstile-144x144.png b/static/mstile-144x144.png Binary files differnew file mode 100644 index 0000000..e54b4bd --- /dev/null +++ b/static/mstile-144x144.png diff --git a/static/mstile-150x150.png b/static/mstile-150x150.png Binary files differnew file mode 100644 index 0000000..c7b84c6 --- /dev/null +++ b/static/mstile-150x150.png diff --git a/static/mstile-310x310.png b/static/mstile-310x310.png Binary files differnew file mode 100644 index 0000000..2cde5c0 --- /dev/null +++ b/static/mstile-310x310.png diff --git a/tailwind.config.js b/tailwind.config.js index 142610f..3764829 100644 --- a/tailwind.config.js +++ b/tailwind.config.js @@ -19,64 +19,64 @@ const colors = { primarydark: colorPrimaryDark, primarylight: colorPrimaryLight, blue: { - 50: "#B5E8FD", - 100: "#9CE1FC", - 200: "#6AD2FB", - 300: "#3EC4F9", - 400: "#0CB5F8", + 50: "#E1F6FE", + 100: "#C4EDFD", + 200: "#88DBFC", + 300: "#52CAFA", + 400: "#16B8F8", 500: "#0694CB", - 600: "#0585B7", - 700: "#0577A4", - 800: "#04658B", - 900: "#035677", + 600: "#0577A4", + 700: "#045A7C", + 800: "#02394F", + 900: "#011D28", }, green: { - 50: "#C7F0E3", - 100: "#B3EADA", - 200: "#93E1CA", - 300: "#6FD7B8", - 400: "#4BCDA6", + 50: "#EBF9F5", + 100: "#D3F3E9", + 200: "#ABE8D6", + 300: "#7FDCC0", + 400: "#53D0AA", 500: "#33B991", - 600: "#2DA480", - 700: "#289071", - 800: "#227C61", - 900: "#1C644E", + 600: "#299474", + 700: "#1F7058", + 800: "#154C3B", + 900: "#0A241C", }, steel: { - 50: "#f2fafc", - 100: "#ddf8fa", - 200: "#b0eef5", - 300: "#7adff2", - 400: "#36c2ec", - 500: "#0594cb", - 600: "#0f7dd3", - 700: "#1363ad", - 800: "#134c7f", - 900: "#113d61", + 50: "#E1F6FE", + 100: "#C3EDFE", + 200: "#88DBFC", + 300: "#4CC9FB", + 400: "#15B9F9", + 500: "#0594CB", + 600: "#0477A4", + 700: "#035677", + 800: "#023A50", + 900: "#011D28", }, orange: { - 50: "#F8E8C4", - 100: "#F7E2B6", - 200: "#F4D99F", - 300: "#F1CE83", - 400: "#EEC56D", - 500: "#EBB951", - 600: "#E9B33F", - 700: "#E6AA28", - 800: "#E0A11A", - 900: "#C99117", + 50: "#FFFBE6", + 100: "#FFF7CC", + 200: "#FFEF99", + 300: "#FEE867", + 400: "#FEE034", + 500: "#FCD801", + 600: "#CBAD01", + 700: "#988201", + 800: "#665600", + 900: "#332B00", }, hotpink: { - 50: "#FFBDD6", - 100: "#FFADCD", - 200: "#FF94BD", - 300: "#FF75AA", - 400: "#FF5C9A", + 50: "#FFEBF2", + 100: "#FFD6E6", + 200: "#FFB3D0", + 300: "#FF8AB7", + 400: "#FF66A1", 500: "#FF3F88", - 600: "#FF297B", - 700: "#FF0F6B", - 800: "#FA0060", - 900: "#E00056", + 600: "#FF0062", + 700: "#BD0048", + 800: "#800031", + 900: "#3D0017", }, }; @@ -101,12 +101,13 @@ module.exports = { }, fontWeight: { light: 300, - normal: 400, + normal: 500, semibold: 600, bold: 700, }, extend: { spacing: { + "2px": "2px", "2/3": "66.666667%", }, // See https://github.com/tailwindcss/typography/blob/master/src/styles.js @@ -272,6 +273,7 @@ module.exports = { fontSize: rem(16), lineHeight: round(24 / 16), }, + p: { marginTop: "1em", marginBottom: "1em", @@ -354,19 +356,6 @@ module.exports = { marginTop: "1.5em", marginBottom: "1rem", }, - table: { - fontSize: rem(14), - lineHeight: round(24 / 16), - }, - "tbody td:first-child": { - paddingLeft: rem(21), - }, - "tbody td:last-child": { - paddingRight: rem(21), - }, - "thead th": { - fontSize: rem(18), - }, // new margins p: { @@ -422,19 +411,33 @@ module.exports = { marginTop: "2em", marginBottom: "2em", }, - table: { - fontSize: rem(16), - lineHeight: round(24 / 16), + "thead tr th": { + paddingLeft: "1rem", + paddingRight: "1rem", + paddingBottom: "0.75rem", + }, + td: { + padding: "1rem", }, "tbody td:first-child": { - paddingLeft: rem(21), + paddingLeft: "1rem", }, "tbody td:last-child": { - paddingRight: rem(21), + paddingRight: "1rem", + }, + "thead th:first-child": { + paddingLeft: "1rem", + }, + "thead th:last-child": { + paddingRight: "1rem", }, "thead th": { fontSize: rem(16), }, + table: { + fontSize: rem(16), + lineHeight: round(24 / 16), + }, }, }, }, |
