From 572b9e7590f61e7adff0514178f0edd43f9fe949 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Thu, 20 Jul 2017 09:19:15 +0200 Subject: [PATCH] Clean up the code shortcode use * No markdown needed * No code fence needed See #61 --- content/about/license.md | 6 +- content/content-management/archetypes.md | 36 ++-- content/content-management/authors.md | 24 +-- .../content-management/cross-references.md | 6 +- content/content-management/formats.md | 24 +-- content/content-management/menus.md | 12 +- content/content-management/multilingual.md | 18 +- content/content-management/organization.md | 18 +- content/content-management/shortcodes.md | 66 +++---- content/content-management/summaries.md | 6 +- content/content-management/toc.md | 12 +- content/content-management/types.md | 6 +- content/content-management/urls.md | 24 +-- content/contribute/development.md | 6 +- content/contribute/documentation.md | 36 ++-- content/contribute/themes.md | 12 +- content/functions/GetPage.md | 6 +- content/functions/absurl.md | 6 +- content/functions/adddate.md | 6 +- content/functions/after.md | 6 +- content/functions/apply.md | 18 +- content/functions/base64.md | 6 +- content/functions/default.md | 30 ++-- content/functions/delimit.md | 18 +- content/functions/dict.md | 12 +- content/functions/intersect.md | 6 +- content/functions/len.md | 12 +- content/functions/math.md | 6 +- content/functions/partialCached.md | 6 +- content/functions/relurl.md | 6 +- content/functions/safeURL.md | 18 +- content/functions/shuffle.md | 6 +- content/functions/slice.md | 6 +- content/functions/time.md | 6 +- content/functions/unix.md | 6 +- content/functions/urlize.md | 12 +- content/functions/where.md | 12 +- content/functions/with.md | 6 +- content/getting-started/configuration.md | 30 ++-- content/getting-started/installing.md | 30 ++-- content/getting-started/quick-start.md | 78 +++----- .../deployment-with-rsync.md | 6 +- .../deployment-with-wercker.md | 60 +++---- .../hosting-on-github.md | 12 +- .../hosting-on-gitlab.md | 6 +- content/templates/404.md | 6 +- content/templates/base.md | 18 +- content/templates/data-templates.md | 6 +- content/templates/files.md | 12 +- content/templates/homepage.md | 6 +- content/templates/internal.md | 6 +- content/templates/introduction.md | 36 ++-- content/templates/lists.md | 168 ++++++------------ content/templates/lookup-order.md | 18 +- content/templates/menu-templates.md | 6 +- content/templates/ordering-and-grouping.md | 138 +++++--------- content/templates/partials.md | 12 +- content/templates/robots.md | 6 +- content/templates/section-templates.md | 6 +- content/templates/shortcode-templates.md | 72 +++----- content/templates/single-page-templates.md | 6 +- content/templates/taxonomy-templates.md | 12 +- content/templates/views.md | 18 +- content/themes/installing-and-using-themes.md | 6 +- content/tools/syntax-highlighting.md | 6 +- content/variables/page.md | 6 +- content/variables/site.md | 6 +- content/variables/taxonomy.md | 6 +- 68 files changed, 444 insertions(+), 888 deletions(-) diff --git a/content/about/license.md b/content/about/license.md index 037e62e9b..7575b79c8 100644 --- a/content/about/license.md +++ b/content/about/license.md @@ -148,8 +148,7 @@ _END OF TERMS AND CONDITIONS_ To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives. -{{% code file="apache-notice.txt" download="apache-notice.txt" %}} -``` +{{< code file="apache-notice.txt" download="apache-notice.txt" >}} Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); @@ -163,5 +162,4 @@ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -``` -{{% /code %}} +{{< /code >}} diff --git a/content/content-management/archetypes.md b/content/content-management/archetypes.md index 1c473b6b7..9fc58139b 100644 --- a/content/content-management/archetypes.md +++ b/content/content-management/archetypes.md @@ -37,11 +37,9 @@ hugo new / We can use this pattern to create a new `.md` file in the `posts` section: -{{% code file="archetype-example.sh" %}} -``` +{{< code file="archetype-example.sh" >}} hugo new posts/my-first-post.md -``` -{{% /code %}} +{{< /code >}} {{% note "Override Content Type in a New File" %}} To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command. @@ -100,14 +98,12 @@ When you create a new Hugo project using `hugo new site`, you'll notice that Hug The following examples are from a site that's using `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category. -{{% code file="archetypes/default.md" %}} -``` +{{< code file="archetypes/default.md" >}} +++ tags = ["golang", "hugo"] categories = ["web development"] +++ -``` -{{% /code %}} +{{< /code >}} {{% warning "EOL Characters in Text Editors"%}} If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See the [troubleshooting article on EOF errors](/troubleshooting/eof-error/) for more information.) @@ -117,11 +113,9 @@ If you get an `EOF error` when using `hugo new`, add a carriage return after the With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section: -{{% code file="new-post-from-default.sh" %}} -``` +{{< code file="new-post-from-default.sh" >}} $ hugo new posts/my-new-post.md -``` -{{% /code %}} +{{< /code >}} Hugo then creates a new markdown file with the following front matter: @@ -148,25 +142,21 @@ Suppose your site's `posts` section requires more sophisticated front matter tha ### Create a Custom Archetype -{{% code file="archetypes/posts.md"%}} -``` +{{< code file="archetypes/posts.md">}} +++ description = "" tags = "" categories = "" +++ -``` -{{% /code %}} +{{< /code >}} ### Use a Custom Archetype With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the `posts` content section: -{{% code file="new-post-from-custom.sh" %}} -``` +{{< code file="new-post-from-custom.sh" >}} $ hugo new posts/post-from-custom.md -``` -{{% /code %}} +{{< /code >}} This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`: @@ -186,11 +176,9 @@ title = "post from custom archetype" As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs: -{{% code file="archetypes/functions.md" %}} -``` +{{< code file="archetypes/functions.md" >}} {{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}} -``` -{{% /code %}} +{{< /code >}} {{% note %}} The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/). diff --git a/content/content-management/authors.md b/content/content-management/authors.md index 85606df81..0a0d1799d 100644 --- a/content/content-management/authors.md +++ b/content/content-management/authors.md @@ -30,8 +30,7 @@ You can create a profile containing metadata for each author on your website. Th Let's suppose Alice Allison is a blogger. A simple unique identifier would be `alice`. Now, we have to create a file called `alice.toml` in the `data/_authors/` directory. The following example is the standardized template written in TOML: -{{% code file="data/_authors/alice.toml" %}} -``` +{{< code file="data/_authors/alice.toml" >}} givenName = "Alice" # or firstName as alias familyName = "Allison" # or lastName as alias displayName = "Alice Allison" @@ -50,8 +49,7 @@ weight = 10 [params] random = "whatever you want" -``` -{{% /code %}} +{{< /code >}} All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage. @@ -116,8 +114,7 @@ This is can be done with the `.Social.URL` function. Its only parameter is the n Most articles feature a small section with information about the author at the end. Let's create one containing the author's name, a thumbnail, a (summarized) biography and links to all social networks: -{{% code file="layouts/partials/author-info.html" download="author-info.html" %}} -``` +{{< code file="layouts/partials/author-info.html" download="author-info.html" >}} {{ with .Author }}

{{ .DisplayName }}

{{ .DisplayName }} @@ -128,8 +125,7 @@ Most articles feature a small section with information about the author at the e {{ end }} {{ end }} -``` -{{% /code %}} +{{< /code >}} ## Who Published What? @@ -152,8 +148,7 @@ taxonomies: In the next step we can create a template to list all authors of your website. Later, the list can be accessed at `www.example.com/authors/`. Create a new template in the `layouts/taxonomy/` directory called `authors.term.html`. This template will be exclusively used for this taxonomy. -{{% code file="layouts/taxonomy/author.term.html" download="author.term.html" %}} -``` +{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}}
    {{ range $author, $v := .Data.Terms }} {{ $profile := $.Authors.Get $author }} @@ -164,8 +159,7 @@ In the next step we can create a template to list all authors of your website. L {{ end }}
-``` -{{% /code %}} +{{< /code >}} `.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically). @@ -175,15 +169,13 @@ Last but not least, we have to create the second list that contains all publicat The layout for this page can be defined in the template `layouts/taxonomy/author.html`. -{{% code file="layouts/taxonomy/author.html" download="author.html" %}} -``` +{{< code file="layouts/taxonomy/author.html" download="author.html" >}} {{ range .Data.Pages }}

{{ .Title }}

written by {{ .Author.DisplayName }} {{ .Summary }} {{ end }} -``` -{{% /code %}} +{{< /code >}} The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags. diff --git a/content/content-management/cross-references.md b/content/content-management/cross-references.md index acecc56d3..30af3f272 100644 --- a/content/content-management/cross-references.md +++ b/content/content-management/cross-references.md @@ -57,11 +57,9 @@ If you have the same filename used across multiple sections, you should only use To be sure to get the correct reference in this case, use the full path: -{{% code file="content/meta/my-article.md" copy="false" %}} -``` +{{< code file="content/meta/my-article.md" copy="false" >}} {{}} => /events/my-birthday/ -``` -{{% /code %}} +{{< /code >}} {{< todo >}}Remove this warning when https://github.com/gohugoio/hugo/issues/3703 is released.{{< /todo >}} diff --git a/content/content-management/formats.md b/content/content-management/formats.md index f3b6f8a6c..be84e7cf4 100644 --- a/content/content-management/formats.md +++ b/content/content-management/formats.md @@ -41,14 +41,12 @@ Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Bl #### Example Task List Input -{{% code file="content/my-to-do-list.md" %}} -``` +{{< code file="content/my-to-do-list.md" >}} - [ ] a task list item - [ ] list syntax required - [ ] incomplete - [x] completed -``` -{{% /code %}} +{{< /code >}} #### Example Task List Output @@ -120,12 +118,10 @@ This is not an introduction into actually using MathJax to render typeset mathem The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventurous readers can consult the [Loading and Configuring](http://docs.mathjax.org/en/latest/configuration.html) section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by include a ` -``` -{{% /code %}} +{{< /code >}} One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/partials/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website. @@ -149,8 +145,7 @@ There are multiple ways to remedy this problem. One solution is to simply escape Another option is to tell Markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a `
` `
` block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the `
` is not acceptable. The syntax for instructing Markdown to treat inline text as verbatim is by wrapping it in backticks (`` ` ``). You might have noticed, however, that the text included in between backticks is rendered differently than standard text (on this site these are items highlighted in red). To get around this problem, we could create a new CSS entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the HTML and CSS source that would accomplish this (note this solution was adapted from [this blog post](http://doswa.com/2011/07/20/mathjax-in-markdown.html)---all credit goes to the original author). -{{% code file="mathjax-markdown-solution.html" %}} -``` +{{< code file="mathjax-markdown-solution.html" >}} -``` -{{% /code %}} +{{< /code >}} As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page. -{{% code file="mathjax-style.css" %}} -``` +{{< code file="mathjax-style.css" >}} code.has-jax { font: inherit; font-size: 100%; @@ -192,8 +185,7 @@ code.has-jax { border: inherit; color: #515151; } -``` -{{% /code %}} +{{< /code >}} In the CSS snippet, notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body. diff --git a/content/content-management/menus.md b/content/content-management/menus.md index e7be1b7c8..7c877afc8 100644 --- a/content/content-management/menus.md +++ b/content/content-management/menus.md @@ -120,8 +120,7 @@ You can also add entries to menus that aren’t attached to a piece of content. Here’s an example snippet pulled from a `config.toml`: -{{% code file="config.toml" %}} -``` +{{< code file="config.toml" >}} [[menu.main]] name = "about hugo" pre = "" @@ -133,13 +132,11 @@ Here’s an example snippet pulled from a `config.toml`: pre = "" weight = -100 url = "/getting-started/" -``` -{{% /code %}} +{{< /code >}} Here's the equivalent snippet in a `config.yaml`: -{{% code file="config.yml" %}} -``` +{{< code file="config.yml" >}} --- menu: docs: @@ -153,8 +150,7 @@ menu: Weight: -100 URL: "/getting-started/" --- -``` -{{% /code %}} +{{< /code >}} {{% note %}} The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the value used for `URL` in the above example is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`. diff --git a/content/content-management/multilingual.md b/content/content-management/multilingual.md index 5fa88b98f..e3c65a26d 100644 --- a/content/content-management/multilingual.md +++ b/content/content-management/multilingual.md @@ -23,8 +23,7 @@ You should define the available languages in a `Languages` section in your site The following is an example of a TOML site configuration for a multilingual Hugo project: -{{% code file="config.toml" download="config.toml" %}} -``` +{{< code file="config.toml" download="config.toml" >}} DefaultContentLanguage = "en" copyright = "Everything is mine" @@ -46,8 +45,7 @@ weight = 2 linkedin = "lien-francais" [Languages.fr.navigation] help = "Aide" -``` -{{% /code %}} +{{< /code >}} Anything not defined in a `[Languages]` block will fall back to the global value for that key (e.g., `copyright` for the English [`en`] language). @@ -66,8 +64,7 @@ Only the obvious non-global options can be overridden per language. Examples of Taxonomies and [Blackfriday configuration][config] can also be set per language: -{{% code file="bf-config.toml" %}} -``` +{{< code file="bf-config.toml" >}} [Taxonomies] tag = "tags" @@ -87,8 +84,7 @@ weight = 2 title = "Français" [Languages.fr.Taxonomies] plaque = "plaques" -``` -{{% /code %}} +{{< /code >}} ## Translate Your Content @@ -127,8 +123,7 @@ We will fix this in https://github.com/gohugoio/hugo/issues/2699 To create a list of links to translated content, use a template similar to the following: -{{% code file="layouts/partials/i18nlist.html" %}} -``` +{{< code file="layouts/partials/i18nlist.html" >}} {{ if .IsTranslated }}

{{ i18n "translations" }}

    @@ -139,8 +134,7 @@ To create a list of links to translated content, use a template similar to the f {{ end}}
{{ end }} -``` -{{% /code %}} +{{< /code >}} The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page, or if there are translations---in the case of the homepage, section listing, etc.---a site with only render one language. diff --git a/content/content-management/organization.md b/content/content-management/organization.md index ef9eae8ec..5108ec221 100644 --- a/content/content-management/organization.md +++ b/content/content-management/organization.md @@ -172,14 +172,12 @@ This isn't in the front matter, but is the actual name of the file minus the ext When defined in the front matter, the `slug` can take the place of the filename for the destination. -{{% code file="content/posts/old-post.md" %}} -``` +{{< code file="content/posts/old-post.md" >}} --- title: New Post slug: "new-post" --- -``` -{{% /code %}} +{{< /code >}} This will render to the following destination according to Hugo's default behavior: @@ -195,15 +193,13 @@ yoursite.com/posts/new-post/ A content's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types][]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts. -{{% code file="content/posts/my-post.md" %}} -``` +{{< code file="content/posts/my-post.md" >}} --- title: My Post type: new layout: mylayout --- -``` -{{% /code %}} +{{< /code >}} @@ -73,8 +72,7 @@ You can show content summaries with the following code. You could use the follow {{ end }} {{ end }} -``` -{{% /code %}} +{{< /code >}} Note how the `.Truncated` boolean valuable may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article. diff --git a/content/content-management/toc.md b/content/content-management/toc.md index 631d9ce4e..13da764dc 100644 --- a/content/content-management/toc.md +++ b/content/content-management/toc.md @@ -49,8 +49,7 @@ The built-in `.TableOfContents` variables outputs a `
{{ end }} -``` -{{% /code %}} +{{< /code >}} [base]: /templates/base/ [contentorg]: /content-management/organization/ diff --git a/content/templates/internal.md b/content/templates/internal.md index dd71b3559..022e95c3c 100644 --- a/content/templates/internal.md +++ b/content/templates/internal.md @@ -90,8 +90,7 @@ Users have noticed that enabling Disqus comments when running the Hugo web serve You can create the following `layouts/partials/disqus.html`: -{{% code file="layouts/partials/disqus.html" download="disqus.html" %}} -``` +{{< code file="layouts/partials/disqus.html" download="disqus.html" >}}
comments powered by Disqus -``` -{{% /code %}} +{{< /code >}} The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`. diff --git a/content/templates/introduction.md b/content/templates/introduction.md index 1883d7537..647d580c4 100644 --- a/content/templates/introduction.md +++ b/content/templates/introduction.md @@ -283,8 +283,7 @@ The most easily overlooked concept to understand about Go templates is that `{{ The following shows how to define a variable independent of the context. -{{% code file="tags-range-with-page-variable.html" %}} -``` +{{< code file="tags-range-with-page-variable.html" >}} {{ $title := .Site.Title }}
    {{ range .Params.tags }} @@ -294,8 +293,7 @@ The following shows how to define a variable independent of the context. {{ end }}
-``` -{{% /code %}} +{{< /code >}} {{% note %}} Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well. @@ -305,8 +303,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` `$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context: -{{% code file="range-through-tags-w-global.html" %}} -``` +{{< code file="range-through-tags-w-global.html" >}}
    {{ range .Params.tags }}
  • @@ -315,8 +312,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}`
    • {{ end }}
-``` -{{% /code %}} +{{< /code >}} {{% warning "Don't Redefine the Dot" %}} The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value. @@ -386,8 +382,7 @@ notoc: true Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]: -{{% code file="layouts/partials/toc.html" download="toc.html" %}} -``` +{{< code file="layouts/partials/toc.html" download="toc.html" >}} {{ if not .Params.notoc }} {{end}} -``` -{{% /code %}} +{{< /code >}} We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`. @@ -410,14 +404,12 @@ You can arbitrarily define as many site-level parameters as you want in your [si For instance, you might declare the following: -{{% code file="config.yaml" %}} -``` +{{< code file="config.yaml" >}} params: copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved." twitteruser: "spf13" sidebarrecentlimit: 5 -``` -{{% /code %}} +{{< /code >}} Within a footer layout, you might then declare a `