diff --git a/.cspell.json b/.cspell.json index 1a197ea7b..0958b7645 100644 --- a/.cspell.json +++ b/.cspell.json @@ -34,6 +34,7 @@ "brlink", "Brotli", "Browsersync", + "canonicalization", "canonify", "Catmull", "Catwoman", @@ -61,6 +62,8 @@ "datatable", "DATOCMS", "debugconfig", + "defang", + "Deindent", "DELIM", "dhersam", "digitalcraftsman", @@ -72,17 +75,21 @@ "DRING", "Eiqc", "Eliott", + "embeddable", "Emojify", "Enwrite", "eopkg", "eparis", "errorf", "erroridf", + "esbuild", "Evernote", + "Exif", "exitwp", "expirydate", "Feminella", "firstpost", + "Flickr", "Formspree", "fpath", "Francia", @@ -91,10 +98,12 @@ "funcs", "funcsig", "Garen", + "Garuda", "gcloud", "Getenv", "getjson", "getpage", + "Gitee", "Gmfc", "Goel", "Gohugo", @@ -106,6 +115,7 @@ "govendor", "Gowans", "Grayscale", + "Gregor", "Gruber", "gtag", "gvfs", @@ -141,10 +151,12 @@ "Joomla", "JRBR", "jsonify", + "Karmada", "katex", "keycdn", "KEYVALS", "kubernetes", + "Kubuntu", "Lanczos", "langformatnumber", "lastmod", @@ -152,6 +164,7 @@ "linktitle", "Lipi", "lrwxr", + "Lubuntu", "maingo", "markdownified", "markdownify", @@ -188,6 +201,7 @@ "newparam", "Nichlas", "Nikhil", + "Nikola", "Njjy", "nlist", "nobr", @@ -221,6 +235,7 @@ "Poupin", "prerender", "println", + "Pritchard", "publishdate", "Pygments", "qref", @@ -249,6 +264,7 @@ "safejs", "Samsa", "schemaorg", + "setx", "Shekhar", "Shortcode", "Shortcodes", @@ -257,7 +273,9 @@ "Sindre", "sitemapindex", "sitemapxml", + "slugorfilename", "Smartcrop", + "Sobre", "Sprintf", "Startseite", "strconv", @@ -278,6 +296,7 @@ "Tknx", "TLDR", "TMPDIR", + "toclevels", "TOCSS", "todos", "tojson", @@ -288,6 +307,8 @@ "toyaml", "twitteruser", "Unmarshal", + "unpublishdate", + "Unsharp", "urlize", "urlset", "utimestamp", @@ -301,15 +322,19 @@ "wibble", "wordcount", "workson", + "Wowchemy", "wpxr", "Xbaabbab", + "Xubuntu", "xvzf", "yoyoyo", + "yunbox", "Zgotmpl", + "Zorin", "zzbbaabb", "مدونتي" ], - "language": "en,en-GB,en-US,de,fr", + "language": "en,en-US,de,fr", "allowCompoundWords": true, "files": [ "**/*.md" @@ -331,5 +356,6 @@ "**/news/*", "**/showcase/*" ], - "useGitignore": true + "useGitignore": true, + "enabled": true } diff --git a/.github/stale.yml b/.github/stale.yml index 389205294..1e72eb329 100644 --- a/.github/stale.yml +++ b/.github/stale.yml @@ -17,6 +17,6 @@ markComment: > If you still think this is important, please tell us why. This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions. - + # Comment to post when closing a stale issue. Set to `false` to disable closeComment: false diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml new file mode 100644 index 000000000..30f98a000 --- /dev/null +++ b/.github/workflows/codeql-analysis.yml @@ -0,0 +1,26 @@ +name: "CodeQL" + +on: + schedule: + - cron: "0 0 1 * *" + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + languages: "javascript" + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index 6f68fee18..594621604 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -1,4 +1,4 @@ -name: 'Check spelling' +name: "Check spelling" on: # rebuild any PRs and main branch changes push: branches-ignore: @@ -15,6 +15,7 @@ jobs: - uses: actions/checkout@v3 - uses: streetsidesoftware/cspell-action@v2 with: + check_dot_files: false + incremental_files_only: true inline: warning strict: false - incremental_files_only: true diff --git a/.github/workflows/super-linter.yml b/.github/workflows/super-linter.yml new file mode 100644 index 000000000..efd206960 --- /dev/null +++ b/.github/workflows/super-linter.yml @@ -0,0 +1,41 @@ +name: Super Linter + +on: + workflow_dispatch: + +permissions: + contents: read # to fetch code (actions/checkout) + +jobs: + build: + permissions: + contents: read # to fetch code (actions/checkout) + statuses: write # to mark status of each linter run (github/super-linter/slim) + + name: Lint Code Base + runs-on: ubuntu-latest + if: ${{ github.actor != 'dependabot[bot]' }} + + steps: + - name: Checkout Code + uses: actions/checkout@v3 + + - name: Lint Code Base + uses: github/super-linter/slim@v4 + env: + DEFAULT_BRANCH: master + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + IGNORE_GITIGNORED_FILES: true + LINTER_RULES_PATH: / + LOG_LEVEL: NOTICE + MARKDOWN_CONFIG_FILE: .markdownlint.yaml + SUPPRESS_POSSUM: true + VALIDATE_CSS: false + VALIDATE_EDITORCONFIG: false + VALIDATE_GITLEAKS: false + VALIDATE_HTML: false + VALIDATE_JAVASCRIPT_STANDARD: false + VALIDATE_JSCPD: false + VALIDATE_NATURAL_LANGUAGE: false + VALIDATE_SHELL_SHFMT: false + VALIDATE_XML: false diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 1b76d280e..58f84dc67 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,4 +1,24 @@ # https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md -MD013: false # Line length -MD033: false # Inline HTML +MD002: false +MD003: false +MD004: false +MD007: false +MD012: + maximum: 2 +MD013: false +MD014: false +MD022: false +MD024: false +MD031: false +MD032: false +MD033: false +MD034: false +MD036: false +MD037: false +MD038: false +MD041: false +MD046: false +MD049: false +MD050: false +MD053: false diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 000000000..4ac45b395 --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,6 @@ +**/commands/** +**/functions/** +**/news/** +**/showcase/** +**/zh/** +**/license.md diff --git a/.textlintignore b/.textlintignore new file mode 100644 index 000000000..97a18e37c --- /dev/null +++ b/.textlintignore @@ -0,0 +1,3 @@ +**/news/** +**/showcase/** +**/zh/** \ No newline at end of file diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 4ca64b165..76c6afe3f 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,6 +1,7 @@ { "recommendations": [ + "DavidAnson.vscode-markdownlint", "EditorConfig.EditorConfig", - "esbenp.prettier-vscode", + "streetsidesoftware.code-spell-checker" ] } diff --git a/README.md b/README.md index a2c767b7b..072714a02 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,11 @@ Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast a ## Contributing -We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you. +We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you. -Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository. +Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository. -*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.* +*Pull requests shall **only** contain changes to the actual documentation. However, changes on the codebase of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.* Spelling fixes are most welcomed, and if you want to contribute longer sections to the documentation, it would be great if you had the following criteria in mind when writing: diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_font-family.css b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_font-family.css index 9b451cf1c..440b5efdd 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_font-family.css +++ b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_font-family.css @@ -1,4 +1,4 @@ -/* From http://cssfontstack.com */ +/* From https://www.cssfontstack.com */ code, .code, pre code, .highlight pre { font-family: 'inconsolata',Menlo,Monaco,'Courier New',monospace; } diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_hljs.css b/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_hljs.css deleted file mode 100644 index c49107655..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_hljs.css +++ /dev/null @@ -1,11 +0,0 @@ -/* modified from:*/ -@import 'highlight.js/styles/atom-one-light.css'; - -/* hljs-template-variable covers the handlebars templating*/ -.hljs-template-variable { - color: var(--primary-color); -} - -.hljs-attr { - color: var(--accent-color-light); -} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/assets/index.js b/_vendor/github.com/gohugoio/gohugoioTheme/assets/index.js index e309bdb99..11b320d74 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/assets/index.js +++ b/_vendor/github.com/gohugoio/gohugoioTheme/assets/index.js @@ -1,12 +1,11 @@ -require("typeface-muli") +require('typeface-muli'); import styles from './css/main.css'; -import './js/clipboardjs.js' -import './js/codeblocks.js' -import './js/docsearch.js' -import './js/hljs.js' -import './js/lazysizes.js' -import './js/menutoggle.js' -import './js/scrolldir.js' -import './js/smoothscroll.js' -import './js/tabs.js' -import './js/nojs.js' +import './js/clipboardjs.js'; +import './js/codeblocks.js'; +import './js/docsearch.js'; +import './js/lazysizes.js'; +import './js/menutoggle.js'; +import './js/scrolldir.js'; +import './js/smoothscroll.js'; +import './js/tabs.js'; +import './js/nojs.js'; diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/assets/js/hljs.js b/_vendor/github.com/gohugoio/gohugoioTheme/assets/js/hljs.js deleted file mode 100644 index c2252e783..000000000 --- a/_vendor/github.com/gohugoio/gohugoioTheme/assets/js/hljs.js +++ /dev/null @@ -1,19 +0,0 @@ -var hljs = require('highlight.js/lib/highlight.js'); - -hljs.registerLanguage('bash', require('highlight.js/lib/languages/bash')); -hljs.registerLanguage('css', require('highlight.js/lib/languages/css')); -hljs.registerLanguage('markdown', require('highlight.js/lib/languages/markdown')); -hljs.registerLanguage('diff', require('highlight.js/lib/languages/diff')); -// hljs.registerLanguage('go', require('highlight.js/lib/languages/go')); -hljs.registerLanguage('javascript', require('highlight.js/lib/languages/javascript')); -hljs.registerLanguage('json', require('highlight.js/lib/languages/json')); -hljs.registerLanguage('yaml', require('highlight.js/lib/languages/yaml')); -hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml')); -hljs.registerLanguage('html', require('highlight.js/lib/languages/handlebars')); - -hljs.registerLanguage("go", function(e) { - var t = { keyword: "code output note warning break default func interface select case map struct chan else goto package switch const fallthrough if range end type continue for import return var go defer bool byte complex64 complex128 float32 float64 int8 int16 int32 int64 string uint8 uint16 uint32 uint64 int uint uintptr rune id autoplay Get", literal: "file download copy true false iota nil Pages with", built_in: "append cap close complex highlight copy imag len make new panic print println real recover delete Site Data tweet youtube ref relref vimeo instagram gist figure innershortcode" }; - return { aliases: ["golang","hugo"], k: t, i: "0)&&"visible"!=_(s,"overflow")&&(r=s.getBoundingClientRect(),o=G>r.left&&Wr.top-1&&J500&&i.clientWidth>500?500:370),X=r.expand,Z=X*r.expFactor),re2&&z>2&&!t.hidden?(re=Z,se=0):re=z>1&&se>1&&ie<6?X:0;for(;s=l&&(J=o.top)<=V&&(G=o.right)>=l*Y&&(W=o.left)<=K&&(Q||G||W||J)&&(r.loadHidden||"hidden"!=_(f[s],"visibility"))&&(q&&ie<3&&!h&&(z<3||se<4)||ae(f[s],u))){if(ge(f[s]),c=!0,ie>9)break}else!c&&q&&!a&&ie<4&&se<4&&z>2&&(B[0]||r.preloadAfterLoad)&&(B[0]||!h&&(Q||G||W||J||"auto"!=f[s].getAttribute(r.sizesAttr)))&&(a=B[0]||f[s]);else ge(f[s]);a&&!c&&ge(a)}},ue=function(e){var t,n=0,i=r.throttleDelay,o=r.ricTimeout,a=function(){t=!1,n=s.now(),e()},u=l&&o>49?function(){l(a,{timeout:o}),o!==r.ricTimeout&&(o=r.ricTimeout)}:S((function(){c(a)}),!0);return function(e){var r;(e=!0===e)&&(o=33),t||(t=!0,(r=i-(s.now()-n))<0&&(r=0),e||r<9?u():c(u,r))}}(ce),le=function(e){m(e.target,r.loadedClass),v(e.target,r.loadingClass),y(e.target,de),b(e.target,"lazyloaded")},he=S(le),de=function(e){he({target:e.target})},fe=function(e){var t,n=e.getAttribute(r.srcsetAttr);(t=r.customMedia[e.getAttribute("data-media")||e.getAttribute("media")])&&e.setAttribute("media",t),n&&e.setAttribute("srcset",n)},pe=S((function(e,t,n,i,s){var o,a,u,l,d,f;(d=b(e,"lazybeforeunveil",t)).defaultPrevented||(i&&(n?m(e,r.autosizesClass):e.setAttribute("sizes",i)),a=e.getAttribute(r.srcsetAttr),o=e.getAttribute(r.srcAttr),s&&(l=(u=e.parentNode)&&h.test(u.nodeName||"")),f=t.firesLoad||"src"in e&&(a||o||l),d={target:e},f&&(y(e,oe,!0),clearTimeout(F),F=c(oe,2500),m(e,r.loadingClass),y(e,de,!0)),l&&p.call(u.getElementsByTagName("source"),fe),a?e.setAttribute("srcset",a):o&&!l&&(te.test(e.nodeName)?function(e,t){try{e.contentWindow.location.replace(t)}catch(n){e.src=t}}(e,o):e.src=o),s&&(a||l)&&w(e,{src:o})),e._lazyRace&&delete e._lazyRace,v(e,r.lazyClass),x((function(){(!f||e.complete&&e.naturalWidth>1)&&(f?oe(d):ie--,le(d))}),!0)})),ge=function(e){var t,n=ee.test(e.nodeName),i=n&&(e.getAttribute(r.sizesAttr)||e.getAttribute("sizes")),s="auto"==i;(!s&&q||!n||!e.getAttribute("src")&&!e.srcset||e.complete||g(e,r.errorClass)||!g(e,r.lazyClass))&&(t=b(e,"lazyunveilread").detail,s&&I.updateElem(e,!0,e.offsetWidth),e._lazyRace=!0,ie++,pe(e,t,s,i,n))},me=function(){if(!q)if(s.now()-U<999)c(me,999);else{var e=C((function(){r.loadMode=3,ue()}));q=!0,r.loadMode=3,ue(),a("scroll",(function(){3==r.loadMode&&(r.loadMode=2),e()}),!0)}},{_:function(){U=s.now(),n.elements=t.getElementsByClassName(r.lazyClass),B=t.getElementsByClassName(r.lazyClass+" "+r.preloadClass),Y=r.hFac,a("scroll",ue,!0),a("resize",ue,!0),e.MutationObserver?new MutationObserver(ue).observe(i,{childList:!0,subtree:!0,attributes:!0}):(i.addEventListener("DOMNodeInserted",ue,!0),i.addEventListener("DOMAttrModified",ue,!0),setInterval(ue,999)),a("hashchange",ue,!0),["focus","mouseover","click","load","transitionend","animationend","webkitAnimationEnd"].forEach((function(e){t.addEventListener(e,ue,!0)})),/d$|^c/.test(t.readyState)?me():(a("load",me),t.addEventListener("DOMContentLoaded",ue),c(me,2e4)),n.elements.length?(ce(),x._lsFlush()):ue()},checkElems:ue,unveil:ge}),I=(P=S((function(e,t,n,r){var i,s,o;if(e._lazysizesWidth=r,r+="px",e.setAttribute("sizes",r),h.test(t.nodeName||""))for(s=0,o=(i=t.getElementsByTagName("source")).length;s0)&&"visible"!=_(o,"overflow")&&(r=o.getBoundingClientRect(),s=X>r.left&&Wr.top-1&&J500&&i.clientWidth>500?500:370:r.expand,n._defEx=d,p=d*r.expFactor,g=r.hFac,G=null,et2&&B>2&&!e.hidden?(et=p,rt=0):et=B>1&&rt>1&&nt<6?d:0;o=l&&(J=s.top)<=K&&(X=s.right)>=l*g&&(W=s.left)<=V&&(Q||X||W||J)&&(r.loadHidden||ot(m[o]))&&(F&&nt<3&&!h&&(B<3||rt<4)||st(m[o],c))){if(pt(m[o]),u=!0,nt>9)break}else!u&&F&&!a&&nt<4&&rt<4&&B>2&&(H[0]||r.preloadAfterLoad)&&(H[0]||!h&&(Q||X||W||J||"auto"!=m[o].getAttribute(r.sizesAttr)))&&(a=H[0]||m[o]);else pt(m[o]);a&&!u&&pt(a)}},ut=function(t){var e,n=0,i=r.throttleDelay,s=r.ricTimeout,a=function(){e=!1,n=o.now(),t()},c=l&&s>49?function(){l(a,{timeout:s}),s!==r.ricTimeout&&(s=r.ricTimeout)}:C((function(){u(a)}),!0);return function(t){var r;(t=!0===t)&&(s=33),e||(e=!0,(r=i-(o.now()-n))<0&&(r=0),t||r<9?c():u(c,r))}}(at),ct=function(t){var e=t.target;e._lazyCache?delete e._lazyCache:(it(t),m(e,r.loadedClass),y(e,r.loadingClass),v(e,ht),b(e,"lazyloaded"))},lt=C(ct),ht=function(t){lt({target:t.target})},ft=function(t){var e,n=t.getAttribute(r.srcsetAttr);(e=r.customMedia[t.getAttribute("data-media")||t.getAttribute("media")])&&t.setAttribute("media",e),n&&t.setAttribute("srcset",n)},dt=C((function(t,e,n,i,o){var s,a,c,l,f,d;(f=b(t,"lazybeforeunveil",e)).defaultPrevented||(i&&(n?m(t,r.autosizesClass):t.setAttribute("sizes",i)),a=t.getAttribute(r.srcsetAttr),s=t.getAttribute(r.srcAttr),o&&(l=(c=t.parentNode)&&h.test(c.nodeName||"")),d=e.firesLoad||"src"in t&&(a||s||l),f={target:t},m(t,r.loadingClass),d&&(clearTimeout(z),z=u(it,2500),v(t,ht,!0)),l&&p.call(c.getElementsByTagName("source"),ft),a?t.setAttribute("srcset",a):s&&!l&&(Y.test(t.nodeName)?function(t,e){try{t.contentWindow.location.replace(e)}catch(n){t.src=e}}(t,s):t.src=s),o&&(a||l)&&w(t,{src:s})),t._lazyRace&&delete t._lazyRace,y(t,r.lazyClass),S((function(){var e=t.complete&&t.naturalWidth>1;d&&!e||(e&&m(t,"ls-is-cached"),ct(f),t._lazyCache=!0,u((function(){"_lazyCache"in t&&delete t._lazyCache}),9))}),!0)})),pt=function(t){var e,n=Z.test(t.nodeName),i=n&&(t.getAttribute(r.sizesAttr)||t.getAttribute("sizes")),o="auto"==i;(!o&&F||!n||!t.getAttribute("src")&&!t.srcset||t.complete||g(t,r.errorClass)||!g(t,r.lazyClass))&&(e=b(t,"lazyunveilread").detail,o&&L.updateElem(t,!0,t.offsetWidth),t._lazyRace=!0,nt++,dt(t,e,o,i,n))},gt=function(){if(!F)if(o.now()-U<999)u(gt,999);else{var t=A((function(){r.loadMode=3,ut()}));F=!0,r.loadMode=3,ut(),a("scroll",(function(){3==r.loadMode&&(r.loadMode=2),t()}),!0)}},{_:function(){U=o.now(),n.elements=e.getElementsByClassName(r.lazyClass),H=e.getElementsByClassName(r.lazyClass+" "+r.preloadClass),a("scroll",ut,!0),a("resize",ut,!0),t.MutationObserver?new MutationObserver(ut).observe(i,{childList:!0,subtree:!0,attributes:!0}):(i.addEventListener("DOMNodeInserted",ut,!0),i.addEventListener("DOMAttrModified",ut,!0),setInterval(ut,999)),a("hashchange",ut,!0),["focus","mouseover","click","load","transitionend","animationend","webkitAnimationEnd"].forEach((function(t){e.addEventListener(t,ut,!0)})),/d$|^c/.test(e.readyState)?gt():(a("load",gt),e.addEventListener("DOMContentLoaded",ut),u(gt,2e4)),n.elements.length?(at(),S._lsFlush()):ut()},checkElems:ut,unveil:pt}),L=($=C((function(t,e,n,r){var i,o,s;if(t._lazysizesWidth=r,r+="px",t.setAttribute("sizes",r),h.test(e.nodeName||""))for(o=0,s=(i=e.getElementsByTagName("source")).length;o0&&void 0!==arguments[0]?arguments[0]:{};this.action="function"==typeof e.action?e.action:this.defaultAction,this.target="function"==typeof e.target?e.target:this.defaultTarget,this.text="function"==typeof e.text?e.text:this.defaultText,this.container="object"===r(e.container)?e.container:document.body}},{key:"listenClick",value:function(e){var t=this;this.listener=(0,a.default)(e,"click",(function(e){return t.onClick(e)}))}},{key:"onClick",value:function(e){var t=e.delegateTarget||e.currentTarget;this.clipboardAction&&(this.clipboardAction=null),this.clipboardAction=new s.default({action:this.action(t),target:this.target(t),text:this.text(t),container:this.container,trigger:t,emitter:this})}},{key:"defaultAction",value:function(e){return l("action",e)}},{key:"defaultTarget",value:function(e){var t=l("target",e);if(t)return document.querySelector(t)}},{key:"defaultText",value:function(e){return l("text",e)}},{key:"destroy",value:function(){this.listener.destroy(),this.clipboardAction&&(this.clipboardAction.destroy(),this.clipboardAction=null)}}],[{key:"isSupported",value:function(){var e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:["copy","cut"],t="string"==typeof e?[e]:e,n=!!document.queryCommandSupported;return t.forEach((function(e){n=n&&!!document.queryCommandSupported(e)})),n}}]),t}(o.default);function l(e,t){var n="data-clipboard-"+e;if(t.hasAttribute(n))return t.getAttribute(n)}e.exports=u},function(e,t,n){"use strict";var r,i="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},s=function(){function e(e,t){for(var n=0;n0&&void 0!==arguments[0]?arguments[0]:{};this.action=e.action,this.container=e.container,this.emitter=e.emitter,this.target=e.target,this.text=e.text,this.trigger=e.trigger,this.selectedText=""}},{key:"initSelection",value:function(){this.text?this.selectFake():this.target&&this.selectTarget()}},{key:"selectFake",value:function(){var e=this,t="rtl"==document.documentElement.getAttribute("dir");this.removeFake(),this.fakeHandlerCallback=function(){return e.removeFake()},this.fakeHandler=this.container.addEventListener("click",this.fakeHandlerCallback)||!0,this.fakeElem=document.createElement("textarea"),this.fakeElem.style.fontSize="12pt",this.fakeElem.style.border="0",this.fakeElem.style.padding="0",this.fakeElem.style.margin="0",this.fakeElem.style.position="absolute",this.fakeElem.style[t?"right":"left"]="-9999px";var n=window.pageYOffset||document.documentElement.scrollTop;this.fakeElem.style.top=n+"px",this.fakeElem.setAttribute("readonly",""),this.fakeElem.value=this.text,this.container.appendChild(this.fakeElem),this.selectedText=(0,a.default)(this.fakeElem),this.copyText()}},{key:"removeFake",value:function(){this.fakeHandler&&(this.container.removeEventListener("click",this.fakeHandlerCallback),this.fakeHandler=null,this.fakeHandlerCallback=null),this.fakeElem&&(this.container.removeChild(this.fakeElem),this.fakeElem=null)}},{key:"selectTarget",value:function(){this.selectedText=(0,a.default)(this.target),this.copyText()}},{key:"copyText",value:function(){var e=void 0;try{e=document.execCommand(this.action)}catch(t){e=!1}this.handleResult(e)}},{key:"handleResult",value:function(e){this.emitter.emit(e?"success":"error",{action:this.action,text:this.selectedText,trigger:this.trigger,clearSelection:this.clearSelection.bind(this)})}},{key:"clearSelection",value:function(){this.trigger&&this.trigger.focus(),window.getSelection().removeAllRanges()}},{key:"destroy",value:function(){this.removeFake()}},{key:"action",set:function(){var e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:"copy";if(this._action=e,"copy"!==this._action&&"cut"!==this._action)throw new Error('Invalid "action" value, use either "copy" or "cut"')},get:function(){return this._action}},{key:"target",set:function(e){if(void 0!==e){if(!e||"object"!==(void 0===e?"undefined":i(e))||1!==e.nodeType)throw new Error('Invalid "target" value, use a valid Element');if("copy"===this.action&&e.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if("cut"===this.action&&(e.hasAttribute("readonly")||e.hasAttribute("disabled")))throw new Error('Invalid "target" attribute. You can\'t cut text from elements with "readonly" or "disabled" attributes');this._target=e}},get:function(){return this._target}}]),e}();e.exports=c},function(e,t){e.exports=function(e){var t;if("SELECT"===e.nodeName)e.focus(),t=e.value;else if("INPUT"===e.nodeName||"TEXTAREA"===e.nodeName){var n=e.hasAttribute("readonly");n||e.setAttribute("readonly",""),e.select(),e.setSelectionRange(0,e.value.length),n||e.removeAttribute("readonly"),t=e.value}else{e.hasAttribute("contenteditable")&&e.focus();var r=window.getSelection(),i=document.createRange();i.selectNodeContents(e),r.removeAllRanges(),r.addRange(i),t=r.toString()}return t}},function(e,t){function n(){}n.prototype={on:function(e,t,n){var r=this.e||(this.e={});return(r[e]||(r[e]=[])).push({fn:t,ctx:n}),this},once:function(e,t,n){var r=this;function i(){r.off(e,i),t.apply(n,arguments)}return i._=t,this.on(e,i,n)},emit:function(e){for(var t=[].slice.call(arguments,1),n=((this.e||(this.e={}))[e]||[]).slice(),r=0,i=n.length;r0&&n.parentNode.classList.add("expand")}}},function(e,t,n){n(8)({apiKey:"167e7998590aebda7f9fedcf86bc4a55",indexName:"hugodocs",inputSelector:"#search-input",debug:!0})},function(e,t,n){ +var r;r=function(){return function(t){var e={};function n(r){if(e[r])return e[r].exports;var i=e[r]={i:r,l:!1,exports:{}};return t[r].call(i.exports,i,i.exports,n),i.l=!0,i.exports}return n.m=t,n.c=e,n.d=function(t,e,r){n.o(t,e)||Object.defineProperty(t,e,{enumerable:!0,get:r})},n.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},n.t=function(t,e){if(1&e&&(t=n(t)),8&e)return t;if(4&e&&"object"==typeof t&&t&&t.__esModule)return t;var r=Object.create(null);if(n.r(r),Object.defineProperty(r,"default",{enumerable:!0,value:t}),2&e&&"string"!=typeof t)for(var i in t)n.d(r,i,function(e){return t[e]}.bind(null,i));return r},n.n=function(t){var e=t&&t.__esModule?function(){return t.default}:function(){return t};return n.d(e,"a",e),e},n.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},n.p="",n(n.s=0)}([function(t,e,n){"use strict";var r="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},i=function(){function t(t,e){for(var n=0;n0&&void 0!==arguments[0]?arguments[0]:{};this.action="function"==typeof t.action?t.action:this.defaultAction,this.target="function"==typeof t.target?t.target:this.defaultTarget,this.text="function"==typeof t.text?t.text:this.defaultText,this.container="object"===r(t.container)?t.container:document.body}},{key:"listenClick",value:function(t){var e=this;this.listener=(0,a.default)(t,"click",(function(t){return e.onClick(t)}))}},{key:"onClick",value:function(t){var e=t.delegateTarget||t.currentTarget;this.clipboardAction&&(this.clipboardAction=null),this.clipboardAction=new o.default({action:this.action(e),target:this.target(e),text:this.text(e),container:this.container,trigger:e,emitter:this})}},{key:"defaultAction",value:function(t){return l("action",t)}},{key:"defaultTarget",value:function(t){var e=l("target",t);if(e)return document.querySelector(e)}},{key:"defaultText",value:function(t){return l("text",t)}},{key:"destroy",value:function(){this.listener.destroy(),this.clipboardAction&&(this.clipboardAction.destroy(),this.clipboardAction=null)}}],[{key:"isSupported",value:function(){var t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:["copy","cut"],e="string"==typeof t?[t]:t,n=!!document.queryCommandSupported;return e.forEach((function(t){n=n&&!!document.queryCommandSupported(t)})),n}}]),e}(s.default);function l(t,e){var n="data-clipboard-"+t;if(e.hasAttribute(n))return e.getAttribute(n)}t.exports=c},function(t,e,n){"use strict";var r,i="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},o=function(){function t(t,e){for(var n=0;n0&&void 0!==arguments[0]?arguments[0]:{};this.action=t.action,this.container=t.container,this.emitter=t.emitter,this.target=t.target,this.text=t.text,this.trigger=t.trigger,this.selectedText=""}},{key:"initSelection",value:function(){this.text?this.selectFake():this.target&&this.selectTarget()}},{key:"selectFake",value:function(){var t=this,e="rtl"==document.documentElement.getAttribute("dir");this.removeFake(),this.fakeHandlerCallback=function(){return t.removeFake()},this.fakeHandler=this.container.addEventListener("click",this.fakeHandlerCallback)||!0,this.fakeElem=document.createElement("textarea"),this.fakeElem.style.fontSize="12pt",this.fakeElem.style.border="0",this.fakeElem.style.padding="0",this.fakeElem.style.margin="0",this.fakeElem.style.position="absolute",this.fakeElem.style[e?"right":"left"]="-9999px";var n=window.pageYOffset||document.documentElement.scrollTop;this.fakeElem.style.top=n+"px",this.fakeElem.setAttribute("readonly",""),this.fakeElem.value=this.text,this.container.appendChild(this.fakeElem),this.selectedText=(0,a.default)(this.fakeElem),this.copyText()}},{key:"removeFake",value:function(){this.fakeHandler&&(this.container.removeEventListener("click",this.fakeHandlerCallback),this.fakeHandler=null,this.fakeHandlerCallback=null),this.fakeElem&&(this.container.removeChild(this.fakeElem),this.fakeElem=null)}},{key:"selectTarget",value:function(){this.selectedText=(0,a.default)(this.target),this.copyText()}},{key:"copyText",value:function(){var t=void 0;try{t=document.execCommand(this.action)}catch(e){t=!1}this.handleResult(t)}},{key:"handleResult",value:function(t){this.emitter.emit(t?"success":"error",{action:this.action,text:this.selectedText,trigger:this.trigger,clearSelection:this.clearSelection.bind(this)})}},{key:"clearSelection",value:function(){this.trigger&&this.trigger.focus(),window.getSelection().removeAllRanges()}},{key:"destroy",value:function(){this.removeFake()}},{key:"action",set:function(){var t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:"copy";if(this._action=t,"copy"!==this._action&&"cut"!==this._action)throw new Error('Invalid "action" value, use either "copy" or "cut"')},get:function(){return this._action}},{key:"target",set:function(t){if(void 0!==t){if(!t||"object"!==(void 0===t?"undefined":i(t))||1!==t.nodeType)throw new Error('Invalid "target" value, use a valid Element');if("copy"===this.action&&t.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if("cut"===this.action&&(t.hasAttribute("readonly")||t.hasAttribute("disabled")))throw new Error('Invalid "target" attribute. You can\'t cut text from elements with "readonly" or "disabled" attributes');this._target=t}},get:function(){return this._target}}]),t}();t.exports=u},function(t,e){t.exports=function(t){var e;if("SELECT"===t.nodeName)t.focus(),e=t.value;else if("INPUT"===t.nodeName||"TEXTAREA"===t.nodeName){var n=t.hasAttribute("readonly");n||t.setAttribute("readonly",""),t.select(),t.setSelectionRange(0,t.value.length),n||t.removeAttribute("readonly"),e=t.value}else{t.hasAttribute("contenteditable")&&t.focus();var r=window.getSelection(),i=document.createRange();i.selectNodeContents(t),r.removeAllRanges(),r.addRange(i),e=r.toString()}return e}},function(t,e){function n(){}n.prototype={on:function(t,e,n){var r=this.e||(this.e={});return(r[t]||(r[t]=[])).push({fn:e,ctx:n}),this},once:function(t,e,n){var r=this;function i(){r.off(t,i),e.apply(n,arguments)}return i._=e,this.on(t,i,n)},emit:function(t){for(var e=[].slice.call(arguments,1),n=((this.e||(this.e={}))[t]||[]).slice(),r=0,i=n.length;r0&&n.parentNode.classList.add("expand")}}},function(t,e,n){n(8)({apiKey:"167e7998590aebda7f9fedcf86bc4a55",indexName:"hugodocs",inputSelector:"#search-input",debug:!0})},function(t,e,n){ /*! docsearch 2.6.1 | © Algolia | github.com/algolia/docsearch */ -var r;"undefined"!=typeof self&&self,r=function(){return function(e){var t={};function n(r){if(t[r])return t[r].exports;var i=t[r]={i:r,l:!1,exports:{}};return e[r].call(i.exports,i,i.exports,n),i.l=!0,i.exports}return n.m=e,n.c=t,n.d=function(e,t,r){n.o(e,t)||Object.defineProperty(e,t,{configurable:!1,enumerable:!0,get:r})},n.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return n.d(t,"a",t),t},n.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},n.p="",n(n.s=22)}([function(e,t,n){"use strict";var r,i=n(1);function s(e){return e.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g,"\\$&")}e.exports={isArray:null,isFunction:null,isObject:null,bind:null,each:null,map:null,mixin:null,isMsie:function(e){if(void 0===e&&(e=navigator.userAgent),/(msie|trident)/i.test(e)){var t=e.match(/(msie |rv:)(\d+(.\d+)?)/i);if(t)return t[2]}return!1},escapeRegExChars:function(e){return e.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g,"\\$&")},isNumber:function(e){return"number"==typeof e},toStr:function(e){return null==e?"":e+""},cloneDeep:function(e){var t=this.mixin({},e),n=this;return this.each(t,(function(e,r){e&&(n.isArray(e)?t[r]=[].concat(e):n.isObject(e)&&(t[r]=n.cloneDeep(e)))})),t},error:function(e){throw new Error(e)},every:function(e,t){var n=!0;return e?(this.each(e,(function(r,i){if(!(n=t.call(null,r,i,e)))return!1})),!!n):n},any:function(e,t){var n=!1;return e?(this.each(e,(function(r,i){if(t.call(null,r,i,e))return n=!0,!1})),n):n},getUniqueId:(r=0,function(){return r++}),templatify:function(e){if(this.isFunction(e))return e;var t=i.element(e);return"SCRIPT"===t.prop("tagName")?function(){return t.text()}:function(){return String(e)}},defer:function(e){setTimeout(e,0)},noop:function(){},formatPrefix:function(e,t){return t?"":e+"-"},className:function(e,t,n){return(n?"":".")+e+t},escapeHighlightedString:function(e,t,n){t=t||"";var r=document.createElement("div");r.appendChild(document.createTextNode(t)),n=n||"";var i=document.createElement("div");i.appendChild(document.createTextNode(n));var o=document.createElement("div");return o.appendChild(document.createTextNode(e)),o.innerHTML.replace(RegExp(s(r.innerHTML),"g"),t).replace(RegExp(s(i.innerHTML),"g"),n)}}},function(e,t,n){"use strict";e.exports={element:null}},function(e,t){var n=Object.prototype.hasOwnProperty,r=Object.prototype.toString;e.exports=function(e,t,i){if("[object Function]"!==r.call(t))throw new TypeError("iterator must be a function");var s=e.length;if(s===+s)for(var o=0;o was loaded but did not call our provided callback"),JSONPScriptError:s("JSONPScriptError"," -{{< /code >}} +```go-html-template +{{ absURL "" }} → https://example.org/docs/ +{{ absURL "articles" }} → https://example.org/docs/articles +{{ absURL "style.css" }} → https://example.org/docs/style.css +``` -The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside ` -{{< /code >}} +```go-html-template +{{ relURL "" }} → /docs/ +{{ relURL "articles" }} → /docs/articles +{{ relURL "style.css" }} → /docs/style.css +``` -The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside ` + ``` diff --git a/content/en/hugo-pipes/introduction.md b/content/en/hugo-pipes/introduction.md index a3c956885..c16572e48 100755 --- a/content/en/hugo-pipes/introduction.md +++ b/content/en/hugo-pipes/introduction.md @@ -4,7 +4,6 @@ linkTitle: Hugo Pipes description: Hugo Pipes is Hugo's asset processing set of functions. date: 2018-07-14 publishdate: 2018-07-14 -lastmod: 2018-07-14 categories: [asset management] keywords: [] menu: @@ -31,10 +30,8 @@ Note that you can mount any directory into Hugo's virtual `assets` folder using | `resources.GetMatch` | `GetMatch` finds the first Resource matching the given pattern, or nil if none found. See Match for a more complete explanation about the rules used. | | `resources.Match` | `Match` gets all resources matching the given base path prefix, e.g "*.png" will match all png files. The "*" does not match path delimiters (/), so if you organize your resources in sub-folders, you need to be explicit about it, e.g.: "images/*.png". To match any PNG image anywhere in the bundle you can do "\*\*.png", and to match all PNG images below the images folder, use "images/\*\*.jpg". The matching is case insensitive. Match matches by using the files name with path relative to the file system root with Unix style slashes (/) and no leading slash, e.g. "images/logo.png". See https://github.com/gobwas/glob for the full rules set.| - See the [GoDoc Page](https://pkg.go.dev/github.com/gohugoio/hugo@v0.93.1/tpl/resources) for the `resources` package for an up to date overview of all template functions in this namespace. - ## Get Resource with resources.Get and resources.GetRemote In order to process an asset with Hugo Pipes, it must be retrieved as a `Resource` using `resources.Get` or `resources.GetRemote`. @@ -68,7 +65,6 @@ With `resources.GetRemote`, the first argument is a remote URL: By default, Hugo calculates a cache key based on the `URL` and the `options` (e.g. headers) given. - {{< new-in "0.97.0" >}} You can override this by setting a `key` in the options map. This can be used to get more fine grained control over how often a remote resource is fetched, e.g.: @@ -79,8 +75,6 @@ By default, Hugo calculates a cache key based on the `URL` and the `options` (e. ### Error Handling -{{< new-in "0.91.0" >}} - The return value from `resources.GetRemote` includes an `.Err` method that will return an error if the call failed. If you want to just log any error as a `WARNING` you can use a construct similar to the one below. ```go-html-template @@ -131,7 +125,7 @@ Asset files must be stored in the asset directory. This is `/assets` by default, ### Asset Publishing -Hugo publishes assets to the to the `publishDir` (typically `public`) when you invoke `.Permalink`, `.RelPermalink`, or `.Publish`. You can use `.Content` to inline the asset. +Hugo publishes assets to the `publishDir` (typically `public`) when you invoke `.Permalink`, `.RelPermalink`, or `.Publish`. You can use `.Content` to inline the asset. ## Go Pipes @@ -156,7 +150,7 @@ The example above can therefore also be written as follows: ## Caching -Hugo Pipes invocations are cached based on the entire _pipe chain_. +Hugo Pipes invocations are cached based on the entire *pipe chain*. An example of a pipe chain is: diff --git a/content/en/hugo-pipes/js.md b/content/en/hugo-pipes/js.md index ff29ca958..c95688e68 100644 --- a/content/en/hugo-pipes/js.md +++ b/content/en/hugo-pipes/js.md @@ -3,7 +3,6 @@ title: JavaScript Building description: Hugo Pipes can process JavaScript files with [ESBuild](https://github.com/evanw/esbuild). date: 2020-07-20 publishdate: 2020-07-20 -lastmod: 2020-07-20 categories: [asset management] keywords: [] menu: @@ -12,7 +11,6 @@ menu: weight: 45 weight: 45 sections_weight: 45 -draft: false --- Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the filepath or a dict of options listed below. @@ -20,33 +18,33 @@ Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build ### Options targetPath [string] -: If not set, the source path will be used as the base target path. +: If not set, the source path will be used as the base target path. Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. -params [map or slice] {{< new-in "0.78.0" >}} +params [map or slice] : Params that can be imported as JSON in your JS files, e.g.: ```go-html-template {{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }} ``` -And then in your JS file: +And then in your JS file: ```js import * as params from '@params'; -``` +``` Note that this is meant for small data sets, e.g. config settings. For larger data, please put/mount the files into `/assets` and import them directly. minify [bool] : Let `js.Build` handle the minification. -inject [slice] {{< new-in "0.81.0" >}} +inject [slice] : This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject -shims {{< new-in "0.81.0" >}} +shims : This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development: -``` +```go-html-template {{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }} {{ $js = $js | js.Build dict "shims" $shims }} ``` @@ -63,17 +61,12 @@ module.exports = window.React; module.exports = window.ReactDOM; ``` - With the above, these imports should work in both scenarios: ```js import * as React from 'react' import * as ReactDOM from 'react-dom'; ``` -sourceMap [string, bool] {{< new-in "0.75.0" >}} -: Let `js.Build` output sourceMap. Current only inline is supported. true defaults to inline. - One of: '`inline`, `external` - Default is "" (disabled) target [string] : The language target. @@ -91,19 +84,17 @@ defines [map] {{ $defines := dict "process.env.NODE_ENV" `"development"` }} ``` -format [string] {{< new-in "0.74.3" >}} +format [string] : The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a + ``` - - diff --git a/content/en/hugo-pipes/minification.md b/content/en/hugo-pipes/minification.md index d11ee58a9..6e539e0e7 100755 --- a/content/en/hugo-pipes/minification.md +++ b/content/en/hugo-pipes/minification.md @@ -3,7 +3,6 @@ title: Asset minification description: Hugo Pipes allows the minification of any CSS, JS, JSON, HTML, SVG or XML resource. date: 2018-07-14 publishdate: 2018-07-14 -lastmod: 2018-07-14 categories: [asset management] keywords: [] menu: @@ -12,13 +11,10 @@ menu: weight: 50 weight: 50 sections_weight: 50 -draft: false --- - Any resource of the aforementioned types can be minified using `resources.Minify` which takes for argument the resource object. - ```go-html-template {{ $css := resources.Get "css/main.css" }} {{ $style := $css | resources.Minify }} diff --git a/content/en/hugo-pipes/postcss.md b/content/en/hugo-pipes/postcss.md index 46833e0a4..b87dc4595 100755 --- a/content/en/hugo-pipes/postcss.md +++ b/content/en/hugo-pipes/postcss.md @@ -3,7 +3,6 @@ title: PostCSS description: Hugo Pipes can process CSS files with PostCSS. date: 2018-07-14 publishdate: 2018-07-14 -lastmod: 2018-07-14 categories: [asset management] keywords: [] menu: @@ -12,10 +11,9 @@ menu: weight: 40 weight: 40 sections_weight: 40 -draft: false --- -Any asset file can be processed using `resources.PostCSS` which takes for argument the resource object and a slice of options listed below. +Any asset file can be processed using `resources.PostCSS` which takes for argument the resource object and a slice of options listed below. The resource will be processed using the project's or theme's own `postcss.config.js` or any file set with the `config` option. @@ -38,15 +36,14 @@ config [string] noMap [bool] : Default is `false`. Disable the default inline sourcemaps -inlineImports [bool] {{< new-in "0.66.0" >}} +inlineImports [bool] : Default is `false`. Enable inlining of @import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. skipInlineImportsNotFound [bool] {{< new-in "0.99.0" >}} - -Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true. +: Default is `false`. Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true. _If no configuration file is used:_ @@ -72,8 +69,6 @@ syntax [string] ## Check Hugo Environment from postcss.config.js -{{< new-in "0.66.0" >}} - The current Hugo environment name (set by `--environment` or in config or OS environment) is available in the Node context, which allows constructs like this: ```js diff --git a/content/en/hugo-pipes/postprocess.md b/content/en/hugo-pipes/postprocess.md index aafb786a4..1aa398356 100755 --- a/content/en/hugo-pipes/postprocess.md +++ b/content/en/hugo-pipes/postprocess.md @@ -12,7 +12,7 @@ weight: 39 sections_weight: 39 --- -Marking a resource with `resources.PostProcess` delays any transformations to after the build, typically because one or more of the steps in the transformation chain depends on the result of the build (e.g. files in `public`).{{< new-in "0.69.0" >}} +Marking a resource with `resources.PostProcess` delays any transformations to after the build, typically because one or more of the steps in the transformation chain depends on the result of the build (e.g. files in `public`). A prime use case for this is [CSS purging with PostCSS](#css-purging-with-postcss). diff --git a/content/en/hugo-pipes/resource-from-string.md b/content/en/hugo-pipes/resource-from-string.md index 8b942d2f3..ae7598ebe 100755 --- a/content/en/hugo-pipes/resource-from-string.md +++ b/content/en/hugo-pipes/resource-from-string.md @@ -4,7 +4,6 @@ linkTitle: Resource from String description: Hugo Pipes allows the creation of a resource from a string. date: 2018-07-14 publishdate: 2018-07-14 -lastmod: 2018-07-14 categories: [asset management] keywords: [] menu: @@ -13,7 +12,6 @@ menu: weight: 90 weight: 90 sections_weight: 90 -draft: false --- It is possible to create a resource directly from the template using `resources.FromString` which takes two arguments, the given string and the resource target path. @@ -26,6 +24,6 @@ The following example creates a resource file containing localized variables for {{ $vars := $string | resources.FromString $targetPath }} {{ $global := resources.Get "js/global.js" | resources.Minify }} - - + + ``` diff --git a/content/en/hugo-pipes/resource-from-template.md b/content/en/hugo-pipes/resource-from-template.md index 9bc8c7e9d..bb0fdb2c2 100755 --- a/content/en/hugo-pipes/resource-from-template.md +++ b/content/en/hugo-pipes/resource-from-template.md @@ -4,7 +4,6 @@ linkTitle: Resource from Template description: Hugo Pipes allows the creation of a resource from an asset file using Go Template. date: 2018-07-14 publishdate: 2018-07-14 -lastmod: 2018-07-14 categories: [asset management] keywords: [] menu: @@ -13,7 +12,6 @@ menu: weight: 80 weight: 80 sections_weight: 80 -draft: false --- In order to use Hugo Pipes function on an asset file containing Go Template magic the function `resources.ExecuteAsTemplate` must be used. @@ -25,13 +23,12 @@ The function takes three arguments: the resource target path, the template conte $backgroundColor: {{ .Param "backgroundColor" }}; $textColor: {{ .Param "textColor" }}; body{ - background-color:$backgroundColor; - color: $textColor; + background-color:$backgroundColor; + color: $textColor; } // [...] ``` - ```go-html-template {{ $sassTemplate := resources.Get "sass/template.scss" }} {{ $style := $sassTemplate | resources.ExecuteAsTemplate "main.scss" . | resources.ToCSS }} diff --git a/content/en/hugo-pipes/scss-sass.md b/content/en/hugo-pipes/scss-sass.md index c4a0a5520..ad4a66b11 100755 --- a/content/en/hugo-pipes/scss-sass.md +++ b/content/en/hugo-pipes/scss-sass.md @@ -1,9 +1,8 @@ --- -title: SASS / SCSS -description: Hugo Pipes allows the processing of SASS and SCSS files. +title: Sass / SCSS +description: Hugo Pipes allows the processing of Sass and SCSS files. date: 2018-07-14 publishdate: 2018-07-14 -lastmod: 2018-07-14 categories: [asset management] keywords: [] menu: @@ -12,11 +11,9 @@ menu: weight: 30 weight: 02 sections_weight: 02 -draft: false --- - -Any SASS or SCSS file can be transformed into a CSS file using `resources.ToCSS` which takes two arguments, the resource object and a map of options listed below. +Any Sass or SCSS file can be transformed into a CSS file using `resources.ToCSS` which takes two arguments, the resource object and a map of options listed below. ```go-html-template {{ $sass := resources.Get "sass/main.scss" }} @@ -25,9 +22,9 @@ Any SASS or SCSS file can be transformed into a CSS file using `resources.ToCSS` ### Options -transpiler [string] {{< new-in "0.80.0" >}} +transpiler [string] -: The `transpiler` to use, valid values are `libsass` (default) and `dartsass`. Note that the Embedded Dart Sass project is still in beta. We will try to improve the installation process when it has stable releases, but if you want to use Hugo with Dart Sass you need to download a release binary from [Embedded Dart Sass](https://github.com/sass/dart-sass-embedded/releases) (Hugo after 0.81.0 requires beta 6 or newer) and make sure it's in your PC's `$PATH` (or `%PATH%` on Windows). +: The `transpiler` to use, valid values are `libsass` (default) and `dartsass`. If you want to use Hugo with Dart Sass you need to download a release binary from [Embedded Dart Sass](https://github.com/sass/dart-sass-embedded/releases) and make sure it's in your PC's `$PATH` (or `%PATH%` on Windows). targetPath [string] : If not set, the resource's target path will be the asset file original path with its extension replaced by `.css`. @@ -42,7 +39,7 @@ enableSourceMap [bool] : When enabled, a source map will be generated. includePaths [string slice] -: Additional SCSS/SASS include paths. Paths must be relative to the project directory. +: Additional SCSS/Sass include paths. Paths must be relative to the project directory. ```go-html-template {{ $options := (dict "targetPath" "style.css" "outputStyle" "compressed" "enableSourceMap" (not hugo.IsProduction) "includePaths" (slice "node_modules/myscss")) }} @@ -50,5 +47,5 @@ includePaths [string slice] ``` {{% note %}} -Setting `outputStyle` to `compressed` will handle SASS/SCSS files minification better than the more generic [`resources.Minify`]({{< ref "minification">}}). +Setting `outputStyle` to `compressed` will handle Sass/SCSS files minification better than the more generic [`resources.Minify`]({{< ref "minification">}}). {{% /note %}} diff --git a/content/en/installation/_index.md b/content/en/installation/_index.md new file mode 100644 index 000000000..e5a34b1f2 --- /dev/null +++ b/content/en/installation/_index.md @@ -0,0 +1,15 @@ +--- +title: Installation +linkTitle: Installation overview +description: Install Hugo on macOS, Linux, Windows, BSD, and on any machine that can run the Go compiler tool chain. +aliases: [/getting-started/installing/] +categories: [installation] +keywords: [installation] +menu: + docs: + parent: installation + weight: 10 +toc: false +--- + +{{% param "description" %}} diff --git a/content/en/installation/bsd.md b/content/en/installation/bsd.md new file mode 100644 index 000000000..f17b64085 --- /dev/null +++ b/content/en/installation/bsd.md @@ -0,0 +1,79 @@ +--- +title: BSD +linkTitle: BSD +description: Install Hugo on BSD derivatives. +categories: [installation] +menu: + docs: + parent: installation + weight: 50 +toc: true +weight: 50 +--- +{{% readfile file="/installation/common/01-editions.md" %}} + +{{% readfile file="/installation/common/02-prerequisites.md" %}} + +{{% readfile file="/installation/common/03-prebuilt-binaries.md" %}} + +## Repository packages + +Most BSD derivatives maintain a repository for commonly installed applications. Please note that these repositories may not contain the [latest release]. + +[latest release]: https://github.com/gohugoio/hugo/releases/latest + +### DragonFly BSD + +[DragonFly BSD] includes Hugo in its package repository. This will install the extended edition of Hugo: + +```sh +sudo pkg install gohugo +``` + +[DragonFly BSD]: https://www.dragonflybsd.org/ + +### FreeBSD + +[FreeBSD] includes Hugo in its package repository. This will install the extended edition of Hugo: + +```sh +sudo pkg install gohugo +``` + +[FreeBSD]: https://www.freebsd.org/ + +### NetBSD + +[NetBSD] includes Hugo in its package repository. This will install the extended edition of Hugo: + +```sh +sudo pkgin install go-hugo +``` + +[NetBSD]: https://www.netbsd.org/ + +### OpenBSD + +[OpenBSD] includes Hugo in its package repository. This will prompt you to select which edition of Hugo to install: + +```sh +doas pkg_add hugo +``` + +[OpenBSD]: https://www.openbsd.org/ + +{{% readfile file="/installation/common/04-docker.md" %}} + +{{% readfile file="/installation/common/05-build-from-source.md" %}} + +## Comparison + +||Prebuilt binaries|Repository packages|Docker|Build from source +:--|:--:|:--:|:--:|:--: +Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:| +Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: +Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: +Automatic updates?|:x:|varies|:x: [^1]|:x: +Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: + +[^1]: Possible but requires advanced configuration. diff --git a/content/en/installation/common/01-editions.md b/content/en/installation/common/01-editions.md new file mode 100644 index 000000000..ee9f3ff93 --- /dev/null +++ b/content/en/installation/common/01-editions.md @@ -0,0 +1,8 @@ +## Editions + +Hugo is available in two editions: standard and extended. With the extended edition you can: + +- Encode WebP images (you can decode WebP images with both editions) +- Transpile Sass to CSS using the embedded LibSass transpiler + +We recommend that you install the extended edition. diff --git a/content/en/installation/common/02-prerequisites.md b/content/en/installation/common/02-prerequisites.md new file mode 100644 index 000000000..008370825 --- /dev/null +++ b/content/en/installation/common/02-prerequisites.md @@ -0,0 +1,27 @@ +## Prerequisites + +Although not required in all cases, Git and Go are often used when working with Hugo. + +Git is required to: + +- Use the [Hugo Modules] feature +- Build Hugo from source +- Install a theme as a Git submodule +- Access [commit information] from a local Git repository +- Host your site with services such as [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify]. + +Go is required to: + +- Use the Hugo Modules feature +- Build Hugo from source + +Please refer to the [Git] and [Go] documentation for installation instructions. + +[AWS Amplify]: https://aws.amazon.com/amplify/ +[CloudCannon]: https://cloudcannon.com/ +[Cloudflare Pages]: https://pages.cloudflare.com/ +[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[GitHub Pages]: https://pages.github.com/ +[GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/ +[Go]: https://go.dev/doc/install +[Netlify]: https://www.netlify.com/ diff --git a/content/en/installation/common/03-prebuilt-binaries.md b/content/en/installation/common/03-prebuilt-binaries.md new file mode 100644 index 000000000..f821f79a2 --- /dev/null +++ b/content/en/installation/common/03-prebuilt-binaries.md @@ -0,0 +1,21 @@ +## Prebuilt binaries + +Prebuilt binaries are available for a variety of operating systems and architectures. Visit the [latest release] page, and scroll down to the Assets section. + + +1. Download the archive for the desired [edition], operating system, and architecture +1. Extract the archive +1. Move the executable to the desired directory +1. Add this directory to the PATH environment variable +1. Verify that you have _execute_ permission on the file + +Please consult your operating system documentation if you need help setting file permissions or modifying your PATH environment variable. + +If you do not see a prebuilt binary for the desired edition, operating system, and architecture, install Hugo using one of the methods described below. + +[commit information]: https://gohugo.io/variables/git +[edition]: #editions +[Git]: https://git-scm.com/ +[Go]: https://go.dev/ +[Hugo Modules]: /hugo-modules/ +[latest release]: https://github.com/gohugoio/hugo/releases/latest diff --git a/content/en/installation/common/04-docker.md b/content/en/installation/common/04-docker.md new file mode 100644 index 000000000..24f5cd942 --- /dev/null +++ b/content/en/installation/common/04-docker.md @@ -0,0 +1,10 @@ +## Docker + +[Erlend Klakegg Bergheim] graciously maintains [Docker images] based on images for Alpine Linux, Busybox, Debian, and Ubuntu. + +```sh +docker pull klakegg/hugo +``` + +[Docker images]: https://hub.docker.com/r/klakegg/hugo +[Erlend Klakegg Bergheim]: https://github.com/klakegg diff --git a/content/en/installation/common/05-build-from-source.md b/content/en/installation/common/05-build-from-source.md new file mode 100644 index 000000000..a135de9fd --- /dev/null +++ b/content/en/installation/common/05-build-from-source.md @@ -0,0 +1,20 @@ +## Build from source + +To build Hugo from source you must: + +1. Install [Git] +1. Install [Go] version 1.18 or later +1. Update your PATH environment variable as described in the [Go documentation] + +> The install directory is controlled by the GOPATH and GOBIN environment variables. If GOBIN is set, binaries are installed to that directory. If GOPATH is set, binaries are installed to the bin subdirectory of the first directory in the GOPATH list. Otherwise, binaries are installed to the bin subdirectory of the default GOPATH ($HOME/go or %USERPROFILE%\go). + +Then build and test: + +```sh +go install -tags extended github.com/gohugoio/hugo@latest +hugo version +``` + +[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[Go]: https://go.dev/doc/install +[Go documentation]: https://go.dev/doc/code#Command diff --git a/content/en/installation/common/homebrew.md b/content/en/installation/common/homebrew.md new file mode 100644 index 000000000..7178a9f4f --- /dev/null +++ b/content/en/installation/common/homebrew.md @@ -0,0 +1,9 @@ +### Homebrew + +[Homebrew] is a free and open source package manager for macOS and Linux. This will install the extended edition of Hugo: + +```sh +brew install hugo +``` + +[Homebrew]: https://brew.sh/ diff --git a/content/en/installation/common/index.md b/content/en/installation/common/index.md new file mode 100644 index 000000000..cbb7365a6 --- /dev/null +++ b/content/en/installation/common/index.md @@ -0,0 +1,3 @@ ++++ +headless = true ++++ diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md new file mode 100644 index 000000000..03ffe9430 --- /dev/null +++ b/content/en/installation/linux.md @@ -0,0 +1,125 @@ +--- +title: Linux +linkTitle: Linux +description: Install Hugo on Linux. +categories: [installation] +menu: + docs: + parent: installation + weight: 30 +toc: true +weight: 30 +--- +{{% readfile file="/installation/common/01-editions.md" %}} + +{{% readfile file="/installation/common/02-prerequisites.md" %}} + +{{% readfile file="/installation/common/03-prebuilt-binaries.md" %}} + +## Package managers + +### Snap + +[Snap] is a free and open source package manager for Linux. Available for [most distributions], Snap packages are simple to install and are automatically updated. This will install the extended edition of Hugo: + +```sh +sudo snap install hugo +``` + +[most distributions]: https://snapcraft.io/docs/installing-snapd +[Snap]: https://snapcraft.io/ + +{{% readfile file="/installation/common/homebrew.md" %}} + +## Repository packages + +Most Linux distributions maintain a repository for commonly installed applications. Please note that these repositories may not contain the [latest release]. + +[latest release]: https://github.com/gohugoio/hugo/releases/latest + +### Arch Linux + +Derivatives of the [Arch Linux] distribution of Linux include [EndeavourOS], [Garuda Linux], [Manjaro], and others. This will install the extended edition of Hugo: + +```sh +sudo pacman -S hugo +``` + +[Arch Linux]: https://archlinux.org/ +[EndeavourOS]: https://endeavouros.com/ +[Manjaro]: https://manjaro.org/ +[Garuda Linux]: https://garudalinux.org/ + +### Debian + +Derivatives of the [Debian] distribution of Linux include [elementary OS], [KDE neon], [Linux Lite], [Linux Mint], [MX Linux], [Pop!_OS], [Ubuntu], [Zorin OS], and others. This will install the extended edition of Hugo: + +```sh +sudo apt install hugo +``` + +You can also download Debian packages from the [latest release] page. + +[Debian]: https://www.debian.org/ +[elementary OS]: https://elementary.io/ +[KDE neon]: https://neon.kde.org/ +[Linux Lite]: https://www.linuxliteos.com/ +[Linux Mint]: https://linuxmint.com/ +[MX Linux]: https://mxlinux.org/ +[Pop!_OS]: https://pop.system76.com/ +[Ubuntu]: https://ubuntu.com/ +[Zorin OS]: https://zorin.com/os/ + +### Fedora + +Derivatives of the [Fedora] distribution of Linux include [CentOS], [Red Hat Enterprise Linux], and others. This will install the extended edition of Hugo: + + +```sh +sudo dnf install hugo +``` + +[CentOS]: https://www.centos.org/ +[Fedora]: https://getfedora.org/ +[Red Hat Enterprise Linux]: https://www.redhat.com/ + +### openSUSE + +Derivatives of the [openSUSE] distribution of Linux include [GeckoLinux], [Linux Karmada], and others. This will install the extended edition of Hugo: + + +```sh +sudo zypper install hugo +``` + +[GeckoLinux]: https://geckolinux.github.io/ +[Linux Karmada]: https://linuxkamarada.com/ +[openSUSE]: https://www.opensuse.org/ + +### Solus + +The [Solus] distribution of Linux includes Hugo in its package repository. This will install the _standard_ edition of Hugo: + +```sh +sudo eopkg install hugo +``` + +[Solus]: https://getsol.us/home/ + +{{% readfile file="/installation/common/04-docker.md" %}} + +{{% readfile file="/installation/common/05-build-from-source.md" %}} + +## Comparison + +||Prebuilt binaries|Package managers|Repository packages|Docker|Build from source +:--|:--:|:--:|:--:|:--:|:--: +Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: +Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: +Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:|:heavy_check_mark: +Automatic updates?|:x:|varies [^2]|:x:|:x: [^3]|:x: +Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:|:heavy_check_mark: + +[^1]: Easy if a previous version is still installed. +[^2]: Snap packages are automatically updated. Homebrew requires advanced configuration. +[^3]: Possible but requires advanced configuration. diff --git a/content/en/installation/macos.md b/content/en/installation/macos.md new file mode 100644 index 000000000..c614f39ba --- /dev/null +++ b/content/en/installation/macos.md @@ -0,0 +1,48 @@ +--- +title: macOS +linkTitle: macOS +description: Install Hugo on macOS. +categories: [installation] +menu: + docs: + parent: installation + weight: 20 +toc: true +weight: 20 +--- +{{% readfile file="/installation/common/01-editions.md" %}} + +{{% readfile file="/installation/common/02-prerequisites.md" %}} + +{{% readfile file="/installation/common/03-prebuilt-binaries.md" %}} + +## Package managers + +{{% readfile file="/installation/common/homebrew.md" %}} + +### MacPorts + +[MacPorts] is a free and open source package manager for macOS. This will install the extended edition of Hugo: + +```sh +sudo port install hugo +``` + +[MacPorts]: https://www.macports.org/ + +{{% readfile file="/installation/common/04-docker.md" %}} + +{{% readfile file="/installation/common/05-build-from-source.md" %}} + +## Comparison + +||Prebuilt binaries|Package managers|Docker|Build from source +:--|:--:|:--:|:--:|:--:|:--: +Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:| +Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: +Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:|:heavy_check_mark: +Automatic updates?|:x:|:x: [^2]|:x: [^2]|:x: +Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: + +[^1]: Easy if a previous version is still installed. +[^2]: Possible but requires advanced configuration. diff --git a/content/en/installation/windows.md b/content/en/installation/windows.md new file mode 100644 index 000000000..6ef17acd4 --- /dev/null +++ b/content/en/installation/windows.md @@ -0,0 +1,63 @@ +--- +title: Windows +linkTitle: Windows +description: Install Hugo on Windows. +categories: [installation] +menu: + docs: + parent: installation + weight: 40 +toc: true +weight: 40 +--- +{{% readfile file="/installation/common/01-editions.md" %}} + +{{% readfile file="/installation/common/02-prerequisites.md" %}} + +{{% readfile file="/installation/common/03-prebuilt-binaries.md" %}} + +## Package managers + +### Chocolatey + +[Chocolatey] is a free and open source package manager for Windows. This will install the extended edition of Hugo: + +```sh +choco install hugo-extended +``` + +[Chocolatey]: https://chocolatey.org/ + +### Scoop + +[Scoop] is a free and open source package manager for Windows. This will install the extended edition of Hugo: + +```sh +scoop install hugo-extended +``` + +[Scoop]: https://scoop.sh/ + +{{% readfile file="/installation/common/04-docker.md" %}} + +{{% readfile file="/installation/common/05-build-from-source.md" %}} + +{{% note %}} +When building the extended edition of Hugo from source on Windows, you will also need to install the [GCC compiler]. See these [detailed instructions]. + +[detailed instructions]: https://discourse.gohugo.io/t/41370 +[GCC compiler]: https://gcc.gnu.org/ +{{% /note %}} + +## Comparison + +||Prebuilt binaries|Package managers|Docker|Build from source +:--|:--:|:--:|:--:|:--:|:--: +Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:| +Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: +Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:|:heavy_check_mark: +Automatic updates?|:x:|:x: [^1]|:x: [^1]|:x: +Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: + +[^1]: Possible but requires advanced configuration. +[^2]: Easy if a previous version is still installed. diff --git a/content/en/news/0.28-relnotes/index.md b/content/en/news/0.28-relnotes/index.md index 91128e48e..4d89d2ac7 100644 --- a/content/en/news/0.28-relnotes/index.md +++ b/content/en/news/0.28-relnotes/index.md @@ -56,7 +56,7 @@ Hugo now has: ### Other * Use Chroma as new default syntax highlighter [fb33d828](https://github.com/gohugoio/hugo/commit/fb33d8286d78a78a74deb44355b621852a1c4033) [@bep](https://github.com/bep) [#3888](https://github.com/gohugoio/hugo/issues/3888) -* Trim newlines in the hightlight shortcode [0d29a0f7](https://github.com/gohugoio/hugo/commit/0d29a0f7819e8d73149701052c29f090cd6db42b) [@bep](https://github.com/bep) [#3898](https://github.com/gohugoio/hugo/issues/3898) +* Trim newlines in the highlight shortcode [0d29a0f7](https://github.com/gohugoio/hugo/commit/0d29a0f7819e8d73149701052c29f090cd6db42b) [@bep](https://github.com/bep) [#3898](https://github.com/gohugoio/hugo/issues/3898) * Update `goorgeous` [b8fabce2](https://github.com/gohugoio/hugo/commit/b8fabce217fcb52e3f273491bef95c7977058732) [@bep](https://github.com/bep) [#3899](https://github.com/gohugoio/hugo/issues/3899) * Add `liveReloadPort` flag to server [b1804776](https://github.com/gohugoio/hugo/commit/b180477631555824a06293053e2b6e63c5f07361) [@bep](https://github.com/bep) [#3882](https://github.com/gohugoio/hugo/issues/3882) * Add `noHTTPCache` flag to hugo server (default on) [0b34af21](https://github.com/gohugoio/hugo/commit/0b34af216154367af7f53ce93d44e6b3d58c3f34) [@bep](https://github.com/bep) [#3897](https://github.com/gohugoio/hugo/issues/3897) diff --git a/content/en/news/0.89.4-relnotes/index.md b/content/en/news/0.89.4-relnotes/index.md index 1f5385f33..f5b24787f 100644 --- a/content/en/news/0.89.4-relnotes/index.md +++ b/content/en/news/0.89.4-relnotes/index.md @@ -1,4 +1,3 @@ - --- date: 2021-11-17 title: "Hugo 0.89.4: One Bug Fix" @@ -6,14 +5,8 @@ description: "This version fixes one bug introduced in 0.89.0." categories: ["Releases"] images: - images/blog/hugo-bug-poster.png - --- - - This is a bug-fix release with one important fix for people using `hugo new` to create new content: * Fix content dir resolution when main project is a Hugo Module [2e70f61f](https://github.com/gohugoio/hugo/commit/2e70f61fb04cea08ef6598728a57637ae2cc199c) [@bep](https://github.com/bep) [#9177](https://github.com/gohugoio/hugo/issues/9177) - - - diff --git a/content/en/readfiles/dateformatting.md b/content/en/readfiles/dateformatting.md index 42138dd8a..2aeb60438 100644 --- a/content/en/readfiles/dateformatting.md +++ b/content/en/readfiles/dateformatting.md @@ -1,12 +1,12 @@ Go templates [format your dates][time] according to a single reference time: -``` +```txt Mon Jan 2 15:04:05 MST 2006 ``` You can think of `MST` as `07`, thus making the reference format string a sequence of numbers. The following is [taken directly from the Go docs][gdex]: -``` +```txt Jan 2 15:04:05 2006 MST 1 2 3 4 5 6 -7 ``` @@ -17,7 +17,7 @@ Each of the following examples show the reference formatting string followed by Note that the examples were rendered and tested in [CST][] and pull from a single example date you might have in your content's front matter: -``` +```yml date: 2017-03-03T14:15:59-06:00 ``` @@ -60,13 +60,13 @@ Spelled-out cardinal numbers (e.g. "one", "two", and "three") and ordinal abbrev To continue with the example above: -``` +```go-html-template {{.Date.Format "Jan 2nd 2006"}} ``` Hugo assumes you want to append `nd` as a string to the day of the month and outputs the following: -``` +```txt Mar 3nd 2017 ``` @@ -84,4 +84,4 @@ In conjunction with the [`dateFormat` function][dateFormat], you can also conver [dateFormat]: /functions/dateformat/ [gdex]: https://golang.org/pkg/time/#example_Time_Format [pagevars]: /variables/page/ -[time]: https://golang.org/pkg/time/ \ No newline at end of file +[time]: https://golang.org/pkg/time/ diff --git a/content/en/readfiles/pages-vs-site-pages.md b/content/en/readfiles/pages-vs-site-pages.md index df5c7d26e..fbf898980 100644 --- a/content/en/readfiles/pages-vs-site-pages.md +++ b/content/en/readfiles/pages-vs-site-pages.md @@ -27,7 +27,7 @@ the current _list_ page: current _list_ page. This **excludes** regular pages in nested sections/_list_ pages (those are subdirectories with an `_index.md` file. `.RegularPagesRecursive` -: {{< new-in "0.68.0" >}} Collection of **all** _regular_ pages under a _list_ page. This **includes** regular pages in nested sections/_list_ pages. +: Collection of **all** _regular_ pages under a _list_ page. This **includes** regular pages in nested sections/_list_ pages. Note : From the scope of _regular_ pages, `.Pages` and diff --git a/content/en/showcase/alora-labs/bio.md b/content/en/showcase/alora-labs/bio.md new file mode 100644 index 000000000..d304cf191 --- /dev/null +++ b/content/en/showcase/alora-labs/bio.md @@ -0,0 +1,3 @@ +**Alora Labs** is a product development consultancy headquartered in Toronto, Canada. + +We help companies build software and IoT products and were recently recognized as one of the [**top IoT development firms**](https://aloralabs.com/insights/alora-labs-receives-clutch-2021-top-iot-agency-award) in Toronto. diff --git a/content/en/showcase/alora-labs/featured.png b/content/en/showcase/alora-labs/featured.png new file mode 100644 index 000000000..b8e1f302b Binary files /dev/null and b/content/en/showcase/alora-labs/featured.png differ diff --git a/content/en/showcase/alora-labs/index.md b/content/en/showcase/alora-labs/index.md new file mode 100644 index 000000000..5e6e18131 --- /dev/null +++ b/content/en/showcase/alora-labs/index.md @@ -0,0 +1,18 @@ +--- +title: Alora Labs +date: 2021-05-27 +description: "Showcase: \"Making performant websites accessible for everyone.\"" +siteURL: https://aloralabs.com/ +siteSource: https://github.com/aloralabs/homepage +aliases: [/showcase/aloralabs/] +--- + +At Alora Labs we always have an eye open for new tools and technology that we can utilize to the benefit of our customers or internal projects like our website. + +The previous iteration of our site was built with Jekyll, which served us well at first. However as time went on, we became frustrated with the number of dependencies we had to rely on, that would often break at the most inconvenient times. + +Hugo was a breath of fresh air in this regard, a single binary that works equally well on Windows as it did on macOS or Linux. We no longer need additional tools for image optimization, Sass compilation or JavaScript bundling. Everything just works, and with a substantial performance boost too. + +Hugo has become a favorite tool in the toolbelt and the foundation for many client projects. We couldn't be happier with the switch and we are optimistic about recommending Hugo for many years to come. + +Thank you to the vibrant community and talented development team for all the hard work in making Hugo a success. As excellent as Hugo is now, we cannot wait to see what the release notes have in store for us next. \ No newline at end of file diff --git a/content/en/showcase/ampio-help/bio.md b/content/en/showcase/ampio-help/bio.md new file mode 100644 index 000000000..c7dd9894a --- /dev/null +++ b/content/en/showcase/ampio-help/bio.md @@ -0,0 +1,11 @@ + +__We are Ampio.__ We design and manufacture a building automation system that provides control, comfort, safety and reliability. Visit [our page](http://ampio.com/) to learn more about our solution! + +__Ampio Knowledge Base__ is a service built and maintained with Hugo. It is a self-service support platform for our customers and certified installers. It also contains a complete portfolio of our modules---building blocks of the Ampio building automation system. + +The site is built by: + +* [@mgetka](https://github.com/mgetka), developer +* [@SteynAnna](https://github.com/SteynAnna), maintainer + +and other members of the Ampio team responsible for content creation. diff --git a/content/en/showcase/ampio-help/featured.png b/content/en/showcase/ampio-help/featured.png new file mode 100644 index 000000000..07974e7f1 Binary files /dev/null and b/content/en/showcase/ampio-help/featured.png differ diff --git a/content/en/showcase/ampio-help/index.md b/content/en/showcase/ampio-help/index.md new file mode 100644 index 000000000..198e62fca --- /dev/null +++ b/content/en/showcase/ampio-help/index.md @@ -0,0 +1,77 @@ +--- +title: Ampio Knowledge Base +date: 2022-10-30 + +description: "Knowledge base for the Ampio building automation system." +siteURL: https://help.ampio.com/ +--- + +As a company that specializes in highly customizable smart solutions for various industries, Ampio has accumulated a vast amount of knowledge throughout the years. We were on the lookout for a user-friendly platform to impart this knowledge to our clients and installers. Delivering a service that caters to both audiences, scattered around the globe with vastly divergent needs and expectations, was a challenge. + +On the one hand, we needed something that would let us educate a client with no technical knowledge about our system in a visually appealing way. + +On the other hand, our installers required technical drawings, offline manuals, and a deep dive into highly specialized subjects. + +Over and above that, we could not overlook the fact that our internal team of editors and maintainers of the Knowledge Base included non-programmers who had to be able to create content and navigate the architecture of the site just as well as those adept at coding. + +We started our journey with the following requirements: + + - Ease of contribution + - Efficient search capabilities + - The possibility of deployment to simple shared hosting + - Proper support for multilingualism + +## Dark ages of WordPress + +With the above-mentioned in mind, we built our first revision of the service in WordPress with a commercial knowledge base plugin. The initial requirements seemed not to be exorbitant, and yet we were surprised to see that only a few of the available solutions covered them. Especially, the case of multilingualism appeared to be particularly neglected across the available products. + +The WordPress-based products made big promises: pay some bucks, bootstrap the service in minutes, and forget about all the development troubles. And although those promises could possibly be deliverable on WordPress' end, it was definitely not true for anything more than the most generic deployments. In our case, we were dealing with more and more trade-offs. Plus, the solution was just slow on the simple shared hosting environment that we dedicated to the job. + +## Turning point + +The turning point was the introduction of a new key requirement---each document was to be downloadable in the PDF format. Such functionality was not available in the plugins we owned, nor did it look like any of the other existing WordPress plugins could fulfill our needs to a satisfactory degree. Nobody in our team was brave enough to add such a functionality to the current stack, so we decided to start from scratch. + +On top of that new development, we had to remember another one of our key requirements, namely, that mostly non-programmers were to be responsible for the service maintenance and content creation. Initially, we were leaning towards headless CMS-based solutions, but finally we made a bold move and decided to create a Git-managed Jamstack service and see what happens. + +## Hugo to the rescue! + +Hugo was our first choice of SSG. The multilingualism support was the primary feature that convinced us. Later on, going through the documentation, we continued to discover new exciting features that we didn't even know we needed when we started. + +The rich functionalities of WordPress WYSIWYG editors soon turned out to be a curse. It became burdensome to maintain formatting consistency across documents prepared by multiple contributors. When we considered Markdown, we knew that it would give us a lot less flexibility. In our case, it proved to be a blessing in disguise---the constraints imposed by the notation ensured that each document was prepared in the same way. And in the cases where Markdown was not enough, Hugo shortcodes gave us all that we needed to get the results we anticipated. + +In terms of PDF generation, we utilized [custom output formats](https://gohugo.io/templates/output-formats/) to produce intermediary document representations, which are consumed by our custom tool transforming them to TeX documents, which are finally used to produce PDF files. + +Custom output formats were also used to create search indexes. The search functionality is built on the brilliant [TNTSearch](https://github.com/teamtnt/tntsearch) library. The search queries and results are handled by PHP snippets embedded into static documents handled by Hugo. + +We even implemented a simple REST API generated by Hugo! We have yet to find something that cannot be achieved with this stack, while in WordPress-based solutions we were struggling with things as simple as defining custom document ordering in one of the categories list views. + +When talking about Hugo, we cannot forget about the speed. At the beginning we were not considering it a killer feature, but as our document base grew bigger, we appreciated it more and more. Dry-runs are not so common---most of the time we are working on one of the documents with cache already built during one of the previous Hugo runs. In such a scenario, Hugo rebuilds the site in about a second and we consider it a very good result. + +``` + | EN | PL +-------------------+-----+------ + Pages | 483 | 486 + Paginator pages | 56 | 55 + Non-page files | 745 | 749 + Static files | 917 | 917 + Processed images | 487 | 490 + Aliases | 80 | 79 + Sitemaps | 2 | 1 + Cleaned | 0 | 0 + +Total in 1096 ms +``` + +## Adaptation among the contributors + +Very quickly it became apparent that our initial concerns about the adaptation of the workflow among contributors were grossly exaggerated. Markdown is fairly straightforward and did not cause any trouble for the contributors. + +We recommended that our colleagues use Visual Studio Code as a tool for content creation. The project’s repository tracks project-scoped configuration of the editor, which includes a set of _tasks_ allowing to run a live server from the GUI level. This is very useful for those who are easily frightened when faced with the mighty terminal. + +The basic skills of the Git workflow were also easily acquired. At the end of the day, builds and deployments are fully managed by CI/CD processes, so the administration of the service drills down to reviewing and accepting merge requests in the Git frontend. As a side effect, we receive a full and clear history of contributions, which is well appreciated by our quality assurance auditors. + +We could even say that our experiment spread the love for Git among non-programmers in our organization! + +## Summary + +Hugo is the best! Definitely give it a try if you are ever faced with a challenge similar to ours. And do not give it a second thought if your service contributors are not too technically inclined---it might still turn out great! diff --git a/content/en/showcase/digitalgov/index.md b/content/en/showcase/digitalgov/index.md index 63f44b645..b06eb355b 100644 --- a/content/en/showcase/digitalgov/index.md +++ b/content/en/showcase/digitalgov/index.md @@ -13,7 +13,7 @@ Through collaboration in our communities of practice, Digital.gov is a window in Digital.gov is built using the [U.S. Web Design System](https://designsystem.digital.gov/) (USWDS) and have followed the [design principles](https://designsystem.digital.gov/maturity-model/) in building out our new site: - **Start with real user needs** — We used human-centered design methods to inform our product decisions (like qualitative user research), and gathered feedback from real users. We also continually test our assumptions with small experiments. -- **Earn trust** —We recognize that trust has to be earned every time. We are including all [required links and content](https://digital.gov/resources/required-web-content-and-links/) on our site, clearly identifying as a government site, building with modern best practices, and using https. +- **Earn trust** —We recognize that trust has to be earned every time. We are including all [required links and content](https://digital.gov/resources/required-web-content-and-links/) on our site, clearly identifying as a government site, building with modern best practices, and using HTTPS. - **Embrace accessibility** — [Accessibility](https://digital.gov/resources/intro-accessibility/) affects everybody, and we built it into every decision. We’re continually working to conform to Section 508 requirements, use user experience best practices, and support a wide range of devices. - **Promote continuity** — We started from shared solutions like USWDS and [Federalist](https://federalist.18f.gov/). We designed our site to clearly identify as a government site by including USWDS’s .gov banner, common colors and patterns, and built with modern best practices. - **Listen** — We actively collect user feedback and web metrics. We use the [Digital Analytics Program](https://digital.gov/services/dap/) (DAP) and analyze the data to discover actionable insights. We make small, incremental changes to continuously improve our website by listening to readers and learning from what we hear. diff --git a/content/en/showcase/fireship/index.md b/content/en/showcase/fireship/index.md index e9338a625..a229e4f6a 100644 --- a/content/en/showcase/fireship/index.md +++ b/content/en/showcase/fireship/index.md @@ -14,4 +14,4 @@ After careful consideration of JavaScript/JSX-based static site generators, it b - **Composability.** Hugo's partial and shortcode systems empower us to write DRY and maintainable templates. - **Simplicity.** Hugo is easy to learn (even without Go experience) and doesn't burden us with brittle dependencies. -The site is able to achieve Lighthouse performance scores of 95+, despite the fact that it is a fully interactive PWA that ships Angular and Firebase in the JS bundle. This is made possible by (1) prerendering content with Hugo and (2) lazily embedding native web components directly in the HTML and markdown. We provide a [detailed explanation](https://youtu.be/gun8OiGtlNc) of the architecture on YouTube and can't imagine development without Hugo. +The site is able to achieve Lighthouse performance scores of 95+, despite the fact that it is a fully interactive PWA that ships Angular and Firebase in the JS bundle. This is made possible by (1) prerendering content with Hugo and (2) lazily embedding native web components directly in the HTML and Markdown. We provide a [detailed explanation](https://youtu.be/gun8OiGtlNc) of the architecture on YouTube and can't imagine development without Hugo. diff --git a/content/en/showcase/forestry/bio.md b/content/en/showcase/forestry/bio.md index 767365cc0..0b8f28743 100644 --- a/content/en/showcase/forestry/bio.md +++ b/content/en/showcase/forestry/bio.md @@ -1,5 +1,4 @@ -Forestry.io is a Git-backed CMS (content management system) for websites and web products built using static site generators such as Hugo. +Forestry.io is a Git-backed CMS (content management system) for websites and web products built using static site generators such as Hugo. Forestry bridges the gap between developers and their teams, by making development fun and easy, while providing powerful content management for their teams. - diff --git a/content/en/showcase/godot-tutorials/bio.md b/content/en/showcase/godot-tutorials/bio.md index 92fccadf6..fd849f844 100644 --- a/content/en/showcase/godot-tutorials/bio.md +++ b/content/en/showcase/godot-tutorials/bio.md @@ -1,9 +1,7 @@ - [Godot Tutorials](https://godottutorials.com) aims to teach beginners how to get up and running with basic game programming and game development skills. The website is built with the **Hugo Framework** alongside aws+cloudfront+lambda. The site is built by: -* [Godot Tutorials](https://godottutorials.com) - +- [Godot Tutorials](https://godottutorials.com) diff --git a/content/en/showcase/godot-tutorials/index.md b/content/en/showcase/godot-tutorials/index.md index e33e413e1..56a8dfc4d 100644 --- a/content/en/showcase/godot-tutorials/index.md +++ b/content/en/showcase/godot-tutorials/index.md @@ -15,11 +15,11 @@ byline: "[Godot Tutorials](https://godottutorials.com), Web Developer & Game Pro [Godot Tutorials](https://godottutorials.com) started as a way to teach beginners game programming and game development. -As I created videos, I ran into a problem; if I made a mistake with a Youtube video, it was difficult to correct errors. +As I created videos, I ran into a problem; if I made a mistake with a YouTube video, it was difficult to correct errors. I discovered that blogging episodes and having articles that teach on top of my videos is a fantastic solution to my problem. -As I researched blogging platforms, I came across two solutions; however, I chose [Hugo](https://gohugo.io) because it's built with markdown in mind and simplified my workflow. +As I researched blogging platforms, I came across two solutions; however, I chose [Hugo](https://gohugo.io) because it's built with Markdown in mind and simplified my workflow. In a sense, with [Hugo](https://gohugo.io) programmed the right way, I can focus **more time on planning, creating, and editing** my videos and **less time maintaining and fixing** my website. \ No newline at end of file diff --git a/content/en/showcase/hapticmedia/index.md b/content/en/showcase/hapticmedia/index.md index 85ec17a8b..7ca2b6cef 100644 --- a/content/en/showcase/hapticmedia/index.md +++ b/content/en/showcase/hapticmedia/index.md @@ -1,28 +1,27 @@ --- - title: Hapticmedia Blog date: 2019-10-01 description: "Showcase: \"A simple, but powerful, multilingual blog.\"" siteURL: https://hapticmedia.fr/blog/en/ byline: "[Cyril Bonnet](https://github.com/monsieurnebo), Web Developer" - --- Our goal was to create a simple, effective and multilingual blog on [3D technology](https://hapticmedia.fr/blog/en/3d-technology/) that could be managed by a non-technical profile. ## Why Hugo? + Hugo addresses all these needs, coupled with [Forestry.io](https://forestry.io/) for its administration via a "turnkey" interface. We have attached particular importance to SEO, and therefore to the creation of an advanced taxonomy system. Thus, each author and tag has a dedicated page, listing the related posts. - ## What we liked + - The **multilingual** content support, especially simple to setup. - The **multiple environments** support (develop, staging, test, production, ...). - Although a hard start with the Go language, the power of the **Hugo's templating**. - The **partial layouts**, including the `internals` (e.g. social meta tags). - The **build time**, unbeatable ⚡️⚡️⚡️. - ## Tools & workflow + - We used the same design as **[our website](https://hapticmedia.fr/en/)**, recreated as a Hugo HTML template. - **[Hugo](https://gohugo.io)** for the static website generator. - **[CircleCI](https://circleci.com)** for continuous integration & deployment. diff --git a/content/en/showcase/hartwell-insurance/index.md b/content/en/showcase/hartwell-insurance/index.md index 925497949..66fc46f44 100644 --- a/content/en/showcase/hartwell-insurance/index.md +++ b/content/en/showcase/hartwell-insurance/index.md @@ -20,7 +20,7 @@ It’s a multi-page, single-page (!) website written in Hugo, a static site gene There’s no Apache or Node backend that does compilation at runtime, it’s all done at the build step. This means the server; Netlify in this case, only has to do one thing – serve files. Unsurprisingly, serving simple files is VERY quick. -The starter point was the [Victor Hugo](https://github.com/netlify/victor-hugo) repository that Netlify have created. It let me dive in with Hugo, PostCSS, BrowserSync and ES6 without setting up any tooling myself – always a win! +The starter point was the [Victor Hugo](https://github.com/netlify/victor-hugo) repository that Netlify have created. It let me dive in with Hugo, PostCSS, Browsersync and ES6 without setting up any tooling myself – always a win! I then took all the content from the design file and moved it into Markdown, putting shortcodes in where necessary. This site did need a number of custom shortcodes for the presentational elements like the expanding circles and full width backgrounds. But mostly it was just clean, semantic HTML with some CSS and JS enhancement thrown in. diff --git a/content/en/showcase/small-multiples/bio.md b/content/en/showcase/small-multiples/bio.md deleted file mode 100644 index 3e0c1f14a..000000000 --- a/content/en/showcase/small-multiples/bio.md +++ /dev/null @@ -1,3 +0,0 @@ - -Small Multiples is a multidisciplinary team of data specialists, designers and developers that help people make the best use of their data, a journey that starts from strategy, to concepts, mock-ups, prototypes, design, and development. - diff --git a/content/en/showcase/small-multiples/featured-small-multiples.png b/content/en/showcase/small-multiples/featured-small-multiples.png deleted file mode 100644 index a278f464d..000000000 Binary files a/content/en/showcase/small-multiples/featured-small-multiples.png and /dev/null differ diff --git a/content/en/showcase/small-multiples/index.md b/content/en/showcase/small-multiples/index.md deleted file mode 100644 index e2b80ea9a..000000000 --- a/content/en/showcase/small-multiples/index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- - -title: Small Multiples -date: 2018-02-28 -description: "\"Hugo has excellent support and integration with Netlify and we were immediately blown away by how fast it was.\"" -siteURL: https://smallmultiples.com.au/ -byline: "[Small Multiples](https://smallmultiples.com.au/)" -draft: true ---- - -Previously we had built and hosted our website with SquareSpace. Although SquareSpace was adequate for quickly showcasing our work, we felt it didn’t reflect our technical capabilities and the types of products we build for our clients. - -For many client applications, static front-end sites provide fast, scalable solutions that can easily connect with any back-end service, API or static data. We wanted to use the same processes and infrastructure that we use to host and deploy many of our products, so we felt that building a static site was the right solution for our website. - -Netlify is a hosting and deployment service that we use for many products. Our developers really like it because it has strong integration with GitHub and it works with the build tools we use such as Yarn and Webpack. It creates a production build every time we commit to our GitHub repository. This means we can share and preview every change internally or with clients. - -Application development has become increasingly complex and there is a strong motivation to simplify this process by avoiding complicated backends in favour of applications that consume static data and APIs (a JAMstack). - -Libraries like React make this easy, but we also wanted something that was server rendered. This led us to look at React based tools for static site generation such as GatsbyJS. We liked GatsbyJS, but in the end, we didn’t choose it due to the lack of availability of a simple CMS driven data source. - -For this, we considered Contentful. Contentful is a beautifully designed application. It’s basically a headless CMS, but it’s not specifically designed for websites and it becomes quite expensive at a commercial level. Their free tier is possibly a good option for personal sites especially with Gatsby. We also evaluated prose.io. This is a free service for editing markdown files in a GitHub repository. It works well, but it’s quite basic and didn’t provide the editing experience we were looking for. - -At the same time, we started exploring Hugo. Hugo is a static site generator similar to Jekyll, but it’s written in Go. It has excellent support and integration with Netlify and we were immediately blown away by how fast it was. - -We had been closely following the redevelopment of the Smashing Magazine website. We knew this was being powered by Hugo and Netlify and this showed us that Hugo could work for a large scale sites. - -The deciding factor, however, was the availability of CMS options that integrate well with Hugo. Netlify has an open source project called NetlifyCMS and there are also hosted services like Forestry.io. These both provide a CMS with an editing interface for markdown files and images. There is no database, instead, changes are committed directly back into the GitHub repository. - -In the end, we chose Hugo on Netlify, with Forestry as our CMS. The site is built and redeployed immediately with Netlify watching for changes to the GitHub repository. - -Was this the right choice? For us, yes, but we learnt a few things along the way. - -The Hugo templating language was very powerful, although also frustrating at times. The queries used to filter list pages are concise but difficult to read. Although it’s easy to get started, Hugo can have a significant learning curve as you try to do more complicated things. - -Hugo has particular expectations when it comes to CMS concepts like tags, categories, RSS, related content and menus. Some parts of our initial design did not match perfectly with how these work in Hugo. It took some time to figure out how to make things work the way we wanted without losing all the benefits of structured content. - -There were a few teething issues. We picked some relatively new technologies and as a result, we encountered some bugs. We were forced to find some workarounds and logged some issues with Hugo during the course of development. Most of these were fixed and features were added with releases happening frequently over the time we were working on the project. This can be exciting but also frustrating. We can see Hugo is developing in the right direction. - -NetlifyCMS was also very new when we first looked at it and this is partly why we opted for Forestry. Forestry is an excellent choice for an out-of-the-box CMS and it needs very little code configuration. It provided a better editing experience for non-technical users. I would still say this is true, but it also provides fewer options for customisation when compared with NetlifyCMS. - -Fortunately, the site is more portable now than it was, or would have been with a dynamic CMS like WordPress, or a fully hosted service like SquareSpace. It should be comparatively easy to swap the publishing functions from Forestry to NetlifyCMS or to change the templates. No part of the pipe-line is tightly coupled, the hosting, the CMS and the templates and the build process can all be updated independently, without changing anything else. - -We have complete control over the design and mark-up produced. This means we can implement a better responsive design and have a stronger focus on accessibility and performance. - -These technology choices gave us a good performance baseline. It was important to implement a site that took advantage of this. As a data visualisation agency, it can be difficult to optimise for performance with a small bundle size, while also aiming for high-quality visuals and working with large datasets. This meant we spent a lot of time optimising assets making sure there was little blocking the critical path for faster rendering and lazy-load images and videos. - -The end result is a high performance site. We think this could have been achieved with GatsbyJS, Hugo or any another static site generator. However, what was important was the decision to use static infrastructure for speed, security, flexibility and hopefully a better ongoing development experience. If you are looking at choosing a static site generator or wondering whether a static is the right choice for you, we hope this has helped. diff --git a/content/en/showcase/template/index.md b/content/en/showcase/template/index.md index 06e4a6548..72707bfde 100644 --- a/content/en/showcase/template/index.md +++ b/content/en/showcase/template/index.md @@ -1,22 +1,18 @@ --- - title: Hugo Showcase Template date: 2018-02-07 description: "A short description of this page." siteURL: https://gohugo.io/ siteSource: https://github.com/gohugoio/hugoDocs byline: "[bep](https://github.com/bep), Hugo Lead" - --- - Have a **notable Hugo site[^1]**? We would love to feature it in this **Showcase Section** -We would really appreciate if you could: +Please: -1. Fork https://github.com/gohugoio/hugoDocs -2. Run `hugo new showcase/your-site` (this requires >= Hugo 0.49). This will use the archetype bundle in the [docs repo](https://github.com/gohugoio/hugoDocs/tree/master/archetypes). +1. Fork https://github.com/gohugoio/hugoDocs. +2. Run `hugo new showcase/your-site`. This will use the archetype bundle in the [docs repo](https://github.com/gohugoio/hugoDocs/tree/master/archetypes). 3. Follow the instructions in the newly created page bundle. -3. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls - +4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls. [^1]: We want this to show Hugo in its best light, so this is not for the average Hugo blog. In most cases the answer to "Is my site [notable](https://www.dictionary.com/browse/notable)?" will be obvious, but if in doubt, create an [issue](https://github.com/gohugoio/hugoDocs/issues) with a link and some words, and we can discuss it. But if you have a site with an interesting Hugo story or a company site where the company itself is notable, you are most welcome. diff --git a/content/en/templates/404.md b/content/en/templates/404.md index 2be629437..81c4c38bd 100644 --- a/content/en/templates/404.md +++ b/content/en/templates/404.md @@ -22,7 +22,7 @@ When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`. -``` +```txt ▾ layouts/ 404.html ``` @@ -52,7 +52,8 @@ Your 404.html file can be set to load automatically when a visitor enters a mist * 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. Use the `handle_errors` directive to specify error pages for one or more status codes. [Details here](https://caddyserver.com/docs/caddyfile/directives/handle_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). +* Azure Static Web App. set `responseOverrides.404.rewrite` and `responseOverrides.404.statusCode` in configfile `staticwebapp.config.json`. [Details here](https://docs.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides) +* Azure Storage as Static Web Site Hosting. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [Details here](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website). * DigitalOcean App Platform. You can specify `error_document` in your app specification file or use control panel to set up error document. [Details here](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site). * [Firebase Hosting](https://firebase.google.com/docs/hosting/full-config#404): `/404.html` automatically gets used as the 404 page. diff --git a/content/en/templates/alternatives.md b/content/en/templates/alternatives.md deleted file mode 100644 index c5fde5b51..000000000 --- a/content/en/templates/alternatives.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: DEPRECATED - Alternative Templating Languages -linktitle: Alternative Templating -description: DEPRECATED - Support for Ace & Amber templating has been removed in version 0.62 -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-20 -categories: [templates] -keywords: [amber,ace,templating languages] -menu: - docs: - parent: "templates" - weight: 170 -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/content/en/templates/base.md b/content/en/templates/base.md index f2648bd52..c82cc09a1 100644 --- a/content/en/templates/base.md +++ b/content/en/templates/base.md @@ -4,7 +4,6 @@ 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). date: 2017-02-01 publishdate: 2017-02-01 -lastmod: 2017-02-01 categories: [templates,fundamentals] keywords: [blocks,base] menu: @@ -24,7 +23,7 @@ The `block` keyword allows you to define the outer shell of your pages' one or m ## 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`). +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. @@ -75,7 +74,7 @@ This replaces the contents of our (basically empty) "main" block with something {{% warning %}} Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example: -``` +```go-html-template {{ define "main" }} ...your code here diff --git a/content/en/templates/data-templates.md b/content/en/templates/data-templates.md index bd1ed6d76..1be4e93eb 100644 --- a/content/en/templates/data-templates.md +++ b/content/en/templates/data-templates.md @@ -4,7 +4,6 @@ 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,xml] menu: @@ -13,7 +12,6 @@ menu: weight: 80 weight: 80 sections_weight: 80 -draft: false aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/] toc: true --- @@ -30,9 +28,23 @@ The `data` folder is where you can store additional data for Hugo to use when ge These files must be YAML, JSON, XML, or TOML files (using the `.yml`, `.yaml`, `.json`, `.xml`, or `.toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable. +If you wish to access the data using the `.Site.Data.filename` notation, the filename must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. eg: + +- `123.json` - Invalid +- `x123.json` - Valid +- `_123.json` - Valid + +If you wish to access the data using the [`index`](/functions/index-function/) function, the filename is irrelevant. For example: +Data file|Template code +:--|:-- +`123.json`|`{{ index .Site.Data "123" }}` +`x123.json`|`{{ index .Site.Data "x123" }}` +`_123.json`|`{{ index .Site.Data "_123" }}` +`x-123.json`|`{{ index .Site.Data "x-123" }}` + ## 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//data` directory). +Data Files can also be used in [Hugo themes][themes] but note that theme data files are merged with the project directory taking precedence (i.e., given two files with the same name and relative path, the data in the file in the root project `data` directory will override the data from the file in the `themes//data` directory *for keys that are duplicated*). 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//somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag. @@ -75,7 +87,7 @@ The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single ba You can now render the list of recordings for all the bass players in a template: -``` +```go-html-template {{ range $.Site.Data.jazz.bass }} {{ partial "artist.html" . }} {{ end }} @@ -83,7 +95,7 @@ You can now render the list of recordings for all the bass players in a template And then in the `partials/artist.html`: -``` +```go-html-template
    {{ range .discography }}
  • {{ . }}
    • @@ -108,7 +120,7 @@ Achievements: You can use the following code to render the `Short Description` in your layout: -``` +```go-html-template
    Short Description of {{.Site.Data.User0123.Name}}:

    {{ index .Site.Data.User0123 "Short Description" | markdownify }}

    ``` @@ -119,14 +131,14 @@ Note the use of the [`markdownify` template function][markdownify]. This will se Use `getJSON` or `getCSV` to get remote data: -``` +```go-html-template {{ $dataJ := getJSON "url" }} {{ $dataC := getCSV "separator" "url" }} ``` If you use a prefix or postfix for the URL, the functions accept [variadic arguments][variadic]: -``` +```go-html-template {{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }} {{ $dataC := getCSV "separator" "url prefix" "arg1" "arg2" "arg n" }} ``` @@ -135,28 +147,28 @@ The separator for `getCSV` must be put in the first position and can only be one All passed arguments will be joined to the final URL: -``` +```go-html-template {{ $urlPre := "https://api.github.com" }} {{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} ``` This will resolve internally to the following: -``` +```go-html-template {{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }} ``` ### Add HTTP headers -{{< new-in "0.84.0" >}} Both `getJSON` and `getCSV` takes an optional map as the last argument, e.g.: +Both `getJSON` and `getCSV` takes an optional map as the last argument, e.g.: -``` +```go-html-template {{ $data := getJSON "https://example.org/api" (dict "Authorization" "Bearer abcd") }} ``` If you need multiple values for the same header key, use a slice: -``` +```go-html-template {{ $data := getJSON "https://example.org/api" (dict "X-List" (slice "a" "b" "c")) }} ``` @@ -197,7 +209,7 @@ With the command-line flag `--cacheDir`, you can specify any folder on your syst 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`. +If you don't like caching at all, you can fully disable caching with the command-line flag `--ignoreCache`. ### Authentication When Using REST URLs @@ -210,7 +222,7 @@ To load local files with `getJSON` and `getCSV`, the source files must reside wi It applies the same output logic as above in [Get Remote Data](#get-remote-data). {{% note %}} -The local CSV files to be loaded using `getCSV` must be located **outside** of the `data` directory. +The local CSV files to be loaded using `getCSV` must be located **outside** the `data` directory. {{% /note %}} ## LiveReload with Data Files diff --git a/content/en/templates/files.md b/content/en/templates/files.md index c2de11292..697863c4c 100644 --- a/content/en/templates/files.md +++ b/content/en/templates/files.md @@ -37,15 +37,15 @@ The [`readfile` function][readFile] reads a file from disk and converts it into To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*: -``` +```go-html-template {{ 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 markdown processor. The pattern for adding this shortcode to your content will be as follows: +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 Markdown processor. The pattern for adding this shortcode to your content will be as follows: -``` +```go-html-template {{}} ``` @@ -53,8 +53,6 @@ As `readFile` is a function, it is only available to you in your templates and n 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 diff --git a/content/en/templates/internal.md b/content/en/templates/internal.md index ace21f548..a92a0f551 100644 --- a/content/en/templates/internal.md +++ b/content/en/templates/internal.md @@ -27,38 +27,42 @@ While the following internal templates are called similar to partials, they do * ## Google Analytics -Hugo ships with internal templates for Google Analytics tracking, including both synchronous and asynchronous tracking codes. As well as support for both v3 and v4 of Google Analytics. +Hugo ships with internal templates supporting Google Analytics, both [Google Analytics 4][GA4] (GA4) and Universal Analytics. + +**Note:** Universal Analytics are deprecated. For details, see [Universal Analytics will be going away][]. + +[GA4]: https://support.google.com/analytics/answer/10089681 +[Universal Analytics will be going away]: https://support.google.com/analytics/answer/11583528 ### Configure Google Analytics -Provide your tracking id in your configuration file: +Provide your tracking ID in your configuration file: -**Google Analytics v3 (analytics.js)** -{{< code-toggle file="config" >}} -googleAnalytics = "UA-PROPERTY_ID" -{{}} - -**Google Analytics v4 (gtag.js)** +**Google Analytics 4 (gtag.js)** {{< code-toggle file="config" >}} googleAnalytics = "G-MEASUREMENT_ID" {{}} +**Google Universal Analytics (analytics.js)** +{{< code-toggle file="config" >}} +googleAnalytics = "UA-PROPERTY_ID" +{{}} + ### Use the Google Analytics Template You can then include the Google Analytics internal template: -``` -{{ template "_internal/google_analytics.html" . }} -``` - - -``` +```go-html-template {{ template "_internal/google_analytics_async.html" . }} ``` -When using Google Analytics v4 use `_internal/google_analytics.html`. +**Note:** The async template is _not_ suitable for Google Analytics 4. -A `.Site.GoogleAnalytics` variable is also exposed from the config. +```go-html-template +{{ template "_internal/google_analytics.html" . }} +``` + +If you want to create your own template, you can access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`. ## Disqus @@ -82,7 +86,7 @@ You also have the option to set the following in the front matter for a given pi To add Disqus, include the following line in templates where you want your comments to appear: -``` +```go-html-template {{ template "_internal/disqus.html" . }} ``` @@ -118,11 +122,12 @@ The `if` statement skips the initialization of the Disqus comment injection when You can then render your custom Disqus partial template as follows: -``` +```go-html-template {{ 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. @@ -167,7 +172,7 @@ If using YouTube this will produce a og:video tag like `}} +[social] + twitter = "GoHugoIO" +{{}} + +NOTE: The `@` will be added for you + +```html + +``` + ### Use the Twitter Cards Template -To add Twitter card metadata, include the following line between the `` tags in your templates: +To add Twitter card metadata, include the following line immediately after the `` element in your templates: -``` +```go-html-template {{ template "_internal/twitter_cards.html" . }} ``` ## The Internal Templates +The code for these templates is located [here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates). + * `_internal/disqus.html` * `_internal/google_analytics.html` * `_internal/google_analytics_async.html` diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index ba66afa86..01f448778 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -4,7 +4,7 @@ linktitle: Templating description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. date: 2017-02-01 publishdate: 2017-02-01 -lastmod: 2017-02-25 +lastmod: 2022-09-20 categories: [templates,fundamentals] keywords: [go] menu: @@ -43,7 +43,7 @@ current scope (like the `.Title` example in the [Variables]({{< relref Parameters for functions are separated using spaces. The general syntax is: -``` +```go-html-template {{ FUNCTION ARG1 ARG2 .. }} ``` @@ -70,8 +70,8 @@ Accessing the Page Parameter `bar` defined in a piece of content's [front matter #### A Single Statement Can be Split over Multiple Lines ```go-html-template -{{ if or - (isset .Params "alt") +{{ if or + (isset .Params "alt") (isset .Params "caption") }} ``` @@ -107,6 +107,7 @@ The custom variables need to be prefixed with `$`. {{ $address := "123 Main St." }} {{ $address }} ``` + Variables can be re-defined using the `=` operator. The example below prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on all other pages: @@ -139,7 +140,7 @@ Go Templates only ship with a few basic functions but also provide a mechanism f ``` -Note that both examples make use of Go Template's [math]][] functions. +Note that both examples make use of Go Template's [math][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). @@ -159,7 +160,7 @@ within Hugo. ### Partial -The [`partial`][partials] function is used to include *partial* templates using +The [`partial`][partials] function is used to include _partial_ templates using the syntax `{{ partial "/." . }}`. Example of including a `layouts/partials/header.html` partial: @@ -170,9 +171,9 @@ Example of including a `layouts/partials/header.html` partial: ### Template -The `template` function was used to include *partial* templates +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_ templates][internal templates]. The syntax is `{{ template "_internal/