diff --git a/.gitignore b/.gitignore index ce7dd6564..eb46f8231 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ report.xml *.cid *.iid *.out +.netlify diff --git a/Makefile b/Makefile index be23be3cd..06d623b23 100644 --- a/Makefile +++ b/Makefile @@ -200,10 +200,10 @@ gen-changelog: docker run -it -v $(shell pwd):/app --workdir /app -e CHANGELOG_GITHUB_TOKEN hairyhenderson/github_changelog_generator \ github_changelog_generator --no-filter-by-milestone --exclude-labels duplicate,question,invalid,wontfix,admin -docs/themes/hugo-material-docs: - git clone https://github.com/digitalcraftsman/hugo-material-docs.git $@ +docs/themes/hugo-theme-relearn: + git clone --depth=1 https://github.com/McShelby/hugo-theme-relearn.git $@ -gen-docs: docs/themes/hugo-material-docs +gen-docs: docs/themes/hugo-theme-relearn cd docs/; hugo docs/content/functions/%.md: docs-src/content/functions/%.yml docs-src/content/functions/func_doc.md.tmpl diff --git a/docs-src/content/functions/func_doc.md.tmpl b/docs-src/content/functions/func_doc.md.tmpl index 36adc7128..9c87dd9f6 100644 --- a/docs-src/content/functions/func_doc.md.tmpl +++ b/docs-src/content/functions/func_doc.md.tmpl @@ -3,11 +3,11 @@ {{- define "usage" }}### Usage {{- $arguments := index . "arguments" | default coll.Slice }} {{ if has . "rawUsage" }}{{ .rawUsage | strings.TrimSpace }}{{ else }} -```go +``` {{ .name }}{{ range $a := $arguments }} {{template "argName" $a }}{{end}} ``` {{- if (index . "pipeline" | default false) }} -```go +``` {{ $last := (sub (len $arguments) 1) -}} {{ (index $arguments $last).name }} | {{ .name }}{{ range $i, $a := $arguments }}{{if not (eq $i $last)}} {{template "argName" $a }}{{end}}{{end}} ``` diff --git a/docs-src/content/functions/sockaddr.yml b/docs-src/content/functions/sockaddr.yml index f50af477a..5992910c0 100644 --- a/docs-src/content/functions/sockaddr.yml +++ b/docs-src/content/functions/sockaddr.yml @@ -15,10 +15,15 @@ preamble: | To demonstrate how this can be used, here's an example that lists all of the IPv4 addresses available on the system: - ```console - $ gomplate -i '{{ range (sockaddr.GetAllInterfaces | sockaddr.Include "type" "ipv4") -}} + _in.tmpl:_ + ``` + {{ range (sockaddr.GetAllInterfaces | sockaddr.Include "type" "ipv4") -}} {{ . | sockaddr.Attr "address" }} - {{end}}' + {{end}} + ``` + + ```console + $ gomplate -f in.tmpl 127.0.0.1 10.0.0.8 132.79.79.79 diff --git a/docs/archetypes/default.md b/docs/archetypes/default.md new file mode 100644 index 000000000..00e77bd79 --- /dev/null +++ b/docs/archetypes/default.md @@ -0,0 +1,6 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +date: {{ .Date }} +draft: true +--- + diff --git a/docs/config.toml b/docs/config.toml index 80ab83493..71e691bf0 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -1,36 +1,51 @@ baseURL = "/" languageCode = "en-us" title = "gomplate documentation" -theme = "hugo-material-docs" +theme = "hugo-theme-relearn" googleAnalytics = "UA-82637990-3" [params] + alwaysopen = false + editURL = "https://github.com/hairyhenderson/gomplate/edit/main/docs/content/" author = "hairyhenderson" description = "gomplate documentation" - copyright = "Released under the MIT license" - provider = "GitHub" - repo_url = "https://github.com/hairyhenderson/gomplate" - logo = "images/gomplate-icon.svg" - favicon = "favicon.ico" - custom_css = [ - "stylesheets/search.css", - "stylesheets/custom-palettes.css", - ] - custom_js = [ - "https://code.jquery.com/jquery-3.3.1.min.js", - "https://cdnjs.cloudflare.com/ajax/libs/fuse.js/3.4.4/fuse.min.js", - "https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/jquery.mark.min.js", - "js/search.js", - "js/faro.js" - ] + showVisitedLinks = false + disableSearch = false + disableSearchHiddenPages = false + disableSeoHiddenPages = false + disableTagHiddenPages = false + disableAssetsBusting = false + disableGeneratorVersion = false + disableInlineCopyToClipBoard = true + disableShortcutsTitle = false + disableLandingPageButton = false + disableLanguageSwitchingButton = false + disableBreadcrumb = false + disableToc = false + disableMathJax = true + disableMermaid = true + disableSwagger = true + disableNextPrev = false + ordersectionsby = "weight" + themeVariantAuto = ["gomplate-light", "gomplate-dark"] + themeVariant = ["auto", "gomplate-light", "gomplate-dark"] + titleSeparator = "-" + collapsibleMenu = true + additionalContentLanguage = [ "en" ] + disableExplicitIndexURLs = true + externalLinkTarget = "_blank" -[params.palette] - primary = "spalding-gray" - accent = "spalding-blue" - -[social] - twitter = "hairyhenderson" - github = "hairyhenderson" +[markup] + [markup.highlight] + guessSyntax = false + noClasses = false [outputs] - home = ["HTML", "RSS", "JSON"] + home = [ "HTML", "RSS", "SEARCH", "SEARCHPAGE"] + +[privacy] + [privacy.googleAnalytics] + disable = false + anonymizeIP = true + respectDoNotTrack = true + useSessionStorage = false diff --git a/docs/content/functions/_index.md b/docs/content/functions/_index.md new file mode 100644 index 000000000..285931907 --- /dev/null +++ b/docs/content/functions/_index.md @@ -0,0 +1,72 @@ +--- +title: Functions +--- + +Almost all of gomplate's utility is provided as _functions._ These are key +words that perform some action. + +For example, the [`base64.Encode`][] function will encode some input string as +a base-64 string: + +``` +The word is {{ base64.Encode "swordfish" }} +``` +renders as: +``` +The word is c3dvcmRmaXNo +``` + +## Built-ins + +Go's [`text/template`][] language provides a number of built-in functions, +operators, and actions that can be used in templates. + +### Built-in functions + +Here is a list of the built-in functions, but see [the documentation](https://golang.org/pkg/text/template/#hdr-Functions) +for full details: + +- `and`, `or`, `not`: Returns boolean AND/OR/NOT of the argument(s). +- `call`: Returns the result of calling a function argument. +- `html`, `js`, `urlquery`: Safely escapes input for inclusion in HTML, JavaScript, and URL query strings. +- `index`: Returns the referenced element of an array/slice, string, or map. See also [Arrays](#arrays) and [Maps](#maps). +- `len`: Returns the length of the argument. +- `print`, `printf`, `println`: Aliases for Go's [`fmt.Print`](https://golang.org/pkg/fmt/#Print), +[`fmt.Printf`](https://golang.org/pkg/fmt/#Printf), and [`fmt.Println`](https://golang.org/pkg/fmt/#Println) +functions. See the [format documentation](https://golang.org/pkg/fmt/#hdr-Printing) +for details on `printf`'s format syntax. + +### Operators + +And the following comparison operators are also supported: + +- `eq`: Equal (`==`) +- `ne`: Not-equal (`!=`) +- `lt`: Less than (`<`) +- `le`: Less than or equal to (`<=`) +- `gt`: Greater than (`>`) +- `ge`: Greater than or equal to (`>=`) + +### Actions + +There are also a few _actions_, which are used for control flow and other purposes. See [the documentation](https://golang.org/pkg/text/template/#hdr-Actions) for details on these: + +- `if`/`else`/`else if`: Conditional control flow. +- `with`/`else`: Conditional execution with assignment. +- `range`: Looping control flow. See discussion in the [Arrays](#arrays) and [Maps](#maps) sections. + - `break`: The innermost `range` loop is ended early, stopping the current iteration and bypassing all remaining iterations. + - `continue`: The current iteration of the innermost `range` loop is stopped, and the loop starts the next iteration. +- `template`: Include the output of a named template. See the [Nested templates](#nested-templates) section for more details, and the [`tmpl`](../functions/tmpl) namespace for more flexible versions of `template`. +- `define`: Define a named nested template. See the [Nested templates](#nested-templates) section for more details. +- `block`: Shorthand for `define` followed immediately by `template`. + +## gomplate functions + +gomplate provides over 200 functions not found in the standard library. These +are grouped into namespaces, and documented on the following pages: + +{{% children depth="3" description="false" %}} + +[`text/template`]: https://golang.org/pkg/text/template/ +[`base64.Encode`]: ../functions/base64#base64-encode +[data sources]: ../datasources/ diff --git a/docs/content/installing.md b/docs/content/installing.md index 144a38056..9b740ef18 100644 --- a/docs/content/installing.md +++ b/docs/content/installing.md @@ -27,7 +27,7 @@ On macOS, you can also install gomplate using [MacPorts](https://www.macports.or $ sudo port install gomplate ``` -## [![Chocolatey](https://img.shields.io/chocolatey/v/gomplate.svg)](https://chocolatey.org/packages/gomplate) Windows with Chocolatey +## Windows with Chocolatey The simplest method for installing gomplate on Windows is to use [`choco`](https://community.chocolatey.org/packages/gomplate): @@ -59,12 +59,11 @@ Of course, there are some drawbacks - any files to be used for [datasources][] must be mounted and any environment variables to be used must be passed through: ```console -$ echo 'My voice is my {{.Env.THING}}. {{(datasource "vault").value}}' \ - | docker run -i -e THING=passport -v /home/me/.vault-token:/root/.vault-token hairyhenderson/gomplate -d vault=vault:///secret/sneakers -f - +$ echo 'My voice is my {{.Env.THING}}. {{(datasource "vault").value}}' | docker run -i -e THING=passport -v /home/me/.vault-token:/root/.vault-token hairyhenderson/gomplate -d vault=vault:///secret/sneakers -f - My voice is my passport. Verify me. ``` -It can be pretty awkward to always type `docker run hairyhenderson/gomplate:stable`, +It can be awkward to always type `docker run hairyhenderson/gomplate:stable`, so this can be made simpler with a shell alias: ```console @@ -145,6 +144,7 @@ $ sh <(curl https://tea.xyz) +gomplate.ca sh $ gomplate --version ... ``` + [releases]: https://github.com/hairyhenderson/gomplate/releases [multi-stage builds]: https://docs.docker.com/develop/develop-images/multistage-build/ [hairyhenderson/gomplate]: https://hub.docker.com/r/hairyhenderson/gomplate/tags/ diff --git a/docs/content/search.md b/docs/content/search.md deleted file mode 100644 index a8bf96103..000000000 --- a/docs/content/search.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Search Results" -sitemap: - priority : 0.1 ---- - -## Results for _""_ - -
-Showing results... -
- -