diff options
| author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2017-09-05 18:09:40 +0200 |
|---|---|---|
| committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2017-09-05 18:09:40 +0200 |
| commit | 16c9127663951ace1a3901cf669c49cc72780ced (patch) | |
| tree | 6a9e43846d5fd9589f36cec934cc456970a7be4a /docs | |
| parent | f88fe312cb35f7de1615c095edd2f898303dd23b (diff) | |
| parent | 7d63a23b0c68d9cd7c7c09c2755619237bc03485 (diff) | |
docs: Merge commit '7d63a23b0c68d9cd7c7c09c2755619237bc03485'
Diffstat (limited to 'docs')
25 files changed, 321 insertions, 90 deletions
diff --git a/docs/content/content-management/formats.md b/docs/content/content-management/formats.md index c2837ffc4..1ff0784a2 100644 --- a/docs/content/content-management/formats.md +++ b/docs/content/content-management/formats.md @@ -214,7 +214,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are * [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial] [`emojify` function]: /functions/emojify/ -[ascii]: http://asciidoc.org/ +[ascii]: http://asciidoctor.org/ [bfconfig]: /getting-started/configuration/#configuring-blackfriday-rendering [blackfriday]: https://github.com/russross/blackfriday [mmark]: https://github.com/miekg/mmark diff --git a/docs/content/content-management/urls.md b/docs/content/content-management/urls.md index 29cd66e84..f6f8df11f 100644 --- a/docs/content/content-management/urls.md +++ b/docs/content/content-management/urls.md @@ -24,7 +24,7 @@ The default Hugo target directory for your built website is `public/`. However, The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option. {{% note "Default Publish and Content Folders" %}} -These examples use the default values for `publishDir` and `contentDir`; i.e., `publish` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/). +These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/). {{% /note %}} For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively. @@ -149,14 +149,14 @@ Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias <head> <title>https://example.com/posts/my-intended-url</title> <link rel="canonical" href="https://example.com/posts/my-intended-url"/> - <meta name=\"robots\" content=\"noindex\"> + <meta name="robots" content="noindex"> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/> </head> </html> ``` -The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name=\"robots\" content=\"noindex\">` lets search engine bots know they they should not crawl and index your new alias page. +The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name="robots" content="noindex">` lets search engine bots know they they should not crawl and index your new alias page. ### Customize You may customize this alias page by creating an `alias.html` template in the diff --git a/docs/content/functions/NumFmt.md b/docs/content/functions/NumFmt.md index 6300c8e91..9940c47b7 100644 --- a/docs/content/functions/NumFmt.md +++ b/docs/content/functions/NumFmt.md @@ -1,18 +1,18 @@ --- title: lang.NumFmt -description: "Formats a number with a given precision using the requested `decimal`, `grouping`, and `negative` characters." +description: "Formats a number with a given precision using the requested `negative`, `decimal`, and `grouping` options. The `options` parameter is a string consisting of `<negative> <decimal> <grouping>`." godocref: "" workson: [] date: 2017-02-01 publishdate: 2017-02-01 -lastmod: 2017-02-01 +lastmod: 2017-08-21 categories: [functions] #tags: [numbers] menu: docs: parent: "functions" toc: false -signature: ["lang.NumFmt <decimal> <grouping> <negative> <precision> <number>"] +signature: ["lang.NumFmt PRECISION NUMBER [OPTIONS]"] workson: [] hugoversion: relatedfuncs: [] @@ -27,8 +27,9 @@ The default options value is `- . ,`. Numbers greater than or equal to 5 are rounded up. For example, if precision is set to `0`, `1.5` becomes `2`, and `1.4` becomes `1`. ``` -{{ lang.NumFmt "," "." "-" 2 12345.6789 }} → 12.345,68 -{{ lang.NumFmt "." "" "-" 6 -12345.6789 }} → -12345.678900 -{{ lang.NumFmt "." "," "-" 0 -12345.6789 }} → -12,346 -{{ -98765.4321 | lang.NumFmt "." "," "-" 2 }} → -98,765.43 +{{ lang.NumFmt 2 12345.6789 }} → 12,345.68 +{{ lang.NumFmt 2 12345.6789 "- , ." }} → 12.345,68 +{{ lang.NumFmt 0 -12345.6789 "- . ," }} → -12,346 +{{ lang.NumFmt 6 -12345.6789 "- ." }} → -12345.678900 +{{ -98765.4321 | lang.NumFmt 2 }} → -98,765.43 ``` diff --git a/docs/content/functions/countrunes.md b/docs/content/functions/countrunes.md index bcb136f86..8e72602b9 100644 --- a/docs/content/functions/countrunes.md +++ b/docs/content/functions/countrunes.md @@ -15,7 +15,7 @@ workson: [] hugoversion: relatedfuncs: [] deprecated: false -aliases: [/functions/countrunes/,/functions/countwords/] +aliases: [/functions/countrunes/] --- In contrast with `countwords` function, which counts every word in a string, the `countrunes` function determines the number of runes in the content and excludes any whitespace. This has specific utility if you are dealing with CJK-like languages. diff --git a/docs/content/functions/math.md b/docs/content/functions/math.md index 6375ad738..9a53473ec 100644 --- a/docs/content/functions/math.md +++ b/docs/content/functions/math.md @@ -31,35 +31,3 @@ There are 6 basic mathematical operators that can be used in Hugo templates: | `mul` | Multiplies two integers. | `{{mul 2 3}}` → 6 | | `sub` | Subtracts two integers. | `{{sub 3 2}}` → 1 | -## Use `add` with Strings - -You can also use the `add` function with strings. You may like this functionality in many use cases, including creating new variables by combining page- or site-level variables with other strings. - -For example, social media sharing with [Twitter Cards][cards] requires the following `meta` link in your site's `<head>` to display Twitter's ["Summary Card with Large Image"][twtsummary]: - -``` -<meta name="twitter:image" content="https://example.com/images/my-twitter-image.jpg"> -``` - -Let's assume you have an `image` field in the front matter of each of your content files: - -``` ---- -title: My Post -image: my-post-image.jpg ---- -``` - -You can then concatenate the `image` value (string) with the path to your `images` directory in `static` and leverage a URL-related templating function for increased flexibility: - -{{< code file="partials/head/twitter-card.html" >}} -{{$socialimage := add "images/" .Params.image}} -<meta name="twitter:image" content="{{ $socialimage | absURL }}"> -{{< /code >}} - -{{% note %}} -The `add` example above makes use of the [`absURL` function](/functions/absurl/). `absURL` and its relative companion `relURL` is the recommended way to construct URLs in Hugo. -{{% /note %}} - -[cards]: https://dev.twitter.com/cards/overview -[twtsummary]: https://dev.twitter.com/cards/types/summary-large-image
\ No newline at end of file diff --git a/docs/content/getting-started/installing.md b/docs/content/getting-started/installing.md index 46cad2a2b..6485de4ec 100644 --- a/docs/content/getting-started/installing.md +++ b/docs/content/getting-started/installing.md @@ -388,10 +388,10 @@ C:\Hugo\Sites> hugo new site example.com You should now have a directory at `C:\Hugo\Sites\example.com`. Change into that directory and list the contents. You should get output similar to the following: ``` -C:\Hugo\Sites>cd example.com -C:\Hugo\Sites\example.com>dir - Directory of C:\hugo\sites\example.com - +C:\Hugo\Sites> cd example.com +C:\Hugo\Sites\example.com> dir +Directory of C:\hugo\sites\example.com + 04/13/2015 10:44 PM <DIR> . 04/13/2015 10:44 PM <DIR> .. 04/13/2015 10:44 PM <DIR> archetypes @@ -459,7 +459,7 @@ See the [related discussion in the Hugo forums][redhatforum]. ## Upgrade Hugo -Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH`. +Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH` or run `brew upgrade hugo` if using Homebrew. ## Install Pygments (Optional) @@ -481,7 +481,7 @@ Now that you've installed Hugo, read the [Quick Start guide][quickstart] and exp [installgit]: http://git-scm.com/ [installgo]: https://golang.org/dl/ [Path Editor]: https://patheditor2.codeplex.com/ -[pygments]: https://pygments.org +[pygments]: http://pygments.org [quickstart]: /getting-started/quick-start/ [redhatforum]: https://discourse.gohugo.io/t/solved-fedora-copr-repository-out-of-service/2491 [releases]: https://github.com/gohugoio/hugo/releases diff --git a/docs/content/hosting-and-deployment/deployment-with-nanobox.md b/docs/content/hosting-and-deployment/deployment-with-nanobox.md new file mode 100644 index 000000000..c318155f9 --- /dev/null +++ b/docs/content/hosting-and-deployment/deployment-with-nanobox.md @@ -0,0 +1,247 @@ +--- +title: Host-Agnostic Deploys with Nanobox +linktitle: Host-Agnostic Deploys with Nanobox +description: Easily deploy Hugo to AWS, DigitalOcean, Google, Azure, and more... +date: 2017-08-24 +publishdate: 2017-08-24 +lastmod: 2017-08-24 +categories: [hosting and deployment] +#tags: [nanobox,deployment,hosting,aws,digitalocean,azure,google,linode] +authors: [Steve Domino] +menu: + docs: + parent: "hosting-and-deployment" + weight: 05 +weight: 05 +sections_weight: 05 +draft: false +aliases: [/tutorials/deployment-with-nanobox/] +toc: true +--- + + + +## Before You Begin + +Nanobox provides an entire end-to-end workflow for developing and deploying applications. Using Nanobox to deploy also means you'll use it to develop your application. + +{{% note %}} +If you're already using Nanobox and just need deployment instructions, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox) +{{% /note %}} + + +## What You'll Need + +With Nanobox you don't need to worry about having Golang or Hugo installed. They'll be installed as part of the development environment created for you. + +To get started you'll just need the following three items: + +* [A Nanobox Account](https://nanobox.io) - Signup is free +* [Nanobox Desktop](https://dashboard.nanobox.io/download) - The free desktop development tool +* An account with a hosting provider such as: + - [AWS](https://aws.amazon.com/) + - [DigitalOcean](https://www.digitalocean.com/) + - [Linode](https://www.linode.com/) + - Azure (coming) + - Google (coming) + - [Roll Your Own](https://docs.nanobox.io/providers/create/) + +### Before We Begin + +There are a few things to get out of the way before diving into the guide. To deploy, you'll need to make sure you have connected a host account to your Nanobox account, and launched a new application. + +#### Connect a Host Account + +Nanobox lets you choose where to host your application (AWS, DigitalOcean, Google, Azure, etc.). In the [Hosting Accounts](https://dashboard.nanobox.io/provider_accounts) section of your Nanobox dashboard [link your Nanobox account with your host](https://docs.nanobox.io/providers/hosting-accounts/). + +#### Launch a New Application on Nanobox + +[Launching a new app on Nanobox](https://docs.nanobox.io/workflow/launch-app/) is very simple. Navigate to [Launch New App](https://dashboard.nanobox.io/apps/new) in the dashboard, and follow the steps there. You'll be asked to name your app, and select a host and region. + +With those out of the way you're ready to get started! + + +## Getting Started + +{{% note %}} +If you already have a functioning Hugo app, you can skip to [Configure Hugo to run with Nanobox](#configure-hugo-to-run-with-nanobox) +{{% /note %}} + +To get started, all you'll need an empty project directory. Create a directory wherever you want your application to live and `cd` into it: + +`mkdir path/to/project && cd path/to/project` + +### Configure Hugo to run with Nanobox + +Nanobox uses a simple config file known as a [boxfile.yml](https://docs.nanobox.io/boxfile/) to describe your application's infrastructure. In the root of your project add the following `boxfile.yml`: + +{{< code file="boxfile.yml" >}} +run.config: + + # use the static engine + engine: static + engine.config: + + # tell the engine where to serve static assets from + rel_dir: public + + # enable file watching for live reload + fs_watch: true + + # install hugo + extra_steps: + - bash ./install.sh + +deploy.config: + + # generate site on deploy + extra_steps: + - hugo + +{{< /code >}} + +{{% note %}} +If you already have a functioning Hugo app, which should now be configured, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox). +{{% /note %}} + +### Installing Hugo + +Nanobox uses Docker to create instant, isolated, development environments. Because of this, you'll need to make sure that during development you have Hugo available. + +Do this by add a custom install script at the root of your project that will install Hugo automatically for you: + +{{< code file="install.sh" >}} + +#!/bin/bash + +if [[ ! -f /data/bin/hugo ]]; then + cd /tmp + wget https://github.com/gohugoio/hugo/releases/download/v0.25.1/hugo_0.25.1_Linux-64bit.tar.gz + tar -xzf hugo_0.25.1_Linux-64bit.tar.gz + mv hugo /data/bin/hugo + cd - + rm -rf /tmp/* +fi + +{{< /code >}} + +{{% note %}} +If the install script fails during `nanobox run` you may need to make it executable with `chmod +x install.sh` +{{% /note %}} + +### Generating a New Hugo App + +You'll generate your new application from inside a Nanobox console (this is why you don't need to worry about having Golang or Hugo installed). + +Run the following command to drop into a Nanobox console (inside the VM) where your codebase is mounted: + +``` +nanobox run +``` + + + +Once inside here use the following steps to create a new Hugo application: + +``` +# cd into the /tmp dir to create an app +cd /tmp + +# generate the hugo app +hugo new site app + +# cd back into the /app dir +cd - + +# copy the generated app into the project +shopt -s dotglob +cp -a /tmp/app/* . +``` + +### Install a theme + +`cd` into the `themes` directory and clone the `nanobox-hugo-theme` repo: + +``` +cd themes +git clone https://github.com/sdomino/nanobox-hugo-theme +``` + +To use the theme *either* copy the entire `config.toml` that comes with the theme, or just add the theme to your existing `config.toml` + +``` +# copy the config.toml that comes with the theme +cp ./themes/nanobox-hugo-theme/config.toml config.toml + +# or, add it to your existing config.toml +theme = "nanobox-hugo-theme" +``` + +{{% note %}} +It is not intended that you use the `nanobox-hugo-theme` as your actual theme. It's simply a theme to start with and should be replaced. +{{% /note %}} + +### View Your App + +To view your application simply run the following command from a Nanobox console: + +``` +hugo server --bind="0.0.0.0" --baseUrl=$APP_IP +``` + + + +With that you should be able to visit your app at the given IP:1313 address + +{{% note %}} +You can [add a custom DNS alias](https://docs.nanobox.io/cli/dns/#add) to make it easier to access your app. Run `nanobox dns add local hugo.dev`. After starting your server, visit your app at [hugo.dev:1313](http://hugo.dev:1313) +{{% /note %}} + +### Develop, Develop, Develop + +{{% note %}} +IMPORTANT: One issue we are aware of, and actively investigating, is livereload. Currently, livereload does not work when developing Hugo applications with Nanobox. +{{% /note %}} + +With Hugo installed you're ready to go. Develop Hugo like you would normally (using all the generators, etc.). Once your app is ready to deploy, run `hugo` to generate your static assets and get ready to deploy! + + +## Deploying Hugo with Nanobox + +{{% note %}} +If you haven't already, make sure to [connect a hosting account](#connect-a-host-account) to your Nanobox account, and [launch a new application](#launch-a-new-application-on-nanobox) in the Dashboard. +{{% /note %}} + +To deploy your application to Nanobox you simply need to [link your local codebase](https://docs.nanobox.io/workflow/deploy-code/#add-your-live-app-as-a-remote) to an application you've created on Nanobox. That is done with the following command: + +``` +nanobox remote add <your-app-name> +``` + +{{% note %}} +You may be prompted to login using your ***Nanobox credentials*** at this time +{{% /note %}} + +### Stage Your Application (optional) + +Nanobox gives you the ability to [simulate your production environment locally](https://docs.nanobox.io/workflow/deploy-code/#preview-locally). While staging is optional it's always recommended, so there's no reason not to! + +To stage your app simply run: + +``` +nanobox deploy dry-run +``` + +Now visit your application with the IP address provided. + + + +### Deploy Your Application + +Once everything checks out and you're [ready to deploy](https://docs.nanobox.io/workflow/deploy-code/#deploy-to-production), simply run: + +``` +nanobox deploy +``` + +Within minutes you're Hugo app will be deployed to your host and humming along smoothly. That's it! diff --git a/docs/content/hosting-and-deployment/deployment-with-rsync.md b/docs/content/hosting-and-deployment/deployment-with-rsync.md index 0d18da711..509949c29 100644 --- a/docs/content/hosting-and-deployment/deployment-with-rsync.md +++ b/docs/content/hosting-and-deployment/deployment-with-rsync.md @@ -1,12 +1,12 @@ --- -title: Deployment with Rysnc -linktitle: Deployment with Rysnc +title: Deployment with Rsync +linktitle: Deployment with Rsync description: If you have access to your web host with SSH, you can use a simple rsync one-liner to incrementally deploy your entire Hugo website. date: 2017-02-01 publishdate: 2017-02-01 lastmod: 2017-02-01 categories: [hosting and deployment] -#tags: [rysnc,deployment] +#tags: [rsync,deployment] authors: [Adrien Poupin] menu: docs: diff --git a/docs/content/hosting-and-deployment/hosting-on-github.md b/docs/content/hosting-and-deployment/hosting-on-github.md index bd930b3f4..59433a9e7 100644 --- a/docs/content/hosting-and-deployment/hosting-on-github.md +++ b/docs/content/hosting-and-deployment/hosting-on-github.md @@ -38,11 +38,10 @@ Make sure your `baseURL` key-value in your [site configuration](/getting-started [As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your master branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively: ``` -publishDir: docs +publishDir = "docs" ``` - ``` -publishDir = "docs" +publishDir: docs ``` After running `hugo`, push your master branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project: @@ -217,7 +216,7 @@ cd .. ``` -You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECDT>` repository as well. +You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECT>` repository as well. That's it! Your personal page should be up and running at `https://yourusername.github.io` within a couple minutes. diff --git a/docs/content/hosting-and-deployment/hosting-on-gitlab.md b/docs/content/hosting-and-deployment/hosting-on-gitlab.md index 0b852dde3..00f2cd18d 100644 --- a/docs/content/hosting-and-deployment/hosting-on-gitlab.md +++ b/docs/content/hosting-and-deployment/hosting-on-gitlab.md @@ -38,7 +38,11 @@ cd your-hugo-site In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below. {{< code file="gitlab-ci.yml" >}} -image: publysher/hugo +image: monachus/hugo + +before_script: + - git submodule init + - git submodule update --force pages: script: @@ -70,7 +74,7 @@ git push -u origin master ## Wait for Your Page to Build -That's it! You can now follow the CI agent building your page at https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines. +That's it! You can now follow the CI agent building your page at `https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines`. After the build has passed, your new website is available at `https://<YourUsername>.gitlab.io/<your-hugo-site>/`. diff --git a/docs/content/hosting-and-deployment/hosting-on-netlify.md b/docs/content/hosting-and-deployment/hosting-on-netlify.md index 012c45d2c..ce10c4a5c 100644 --- a/docs/content/hosting-and-deployment/hosting-on-netlify.md +++ b/docs/content/hosting-and-deployment/hosting-on-netlify.md @@ -63,7 +63,7 @@ Once selected, you'll be brought to a screen for basic setup. Here you can selec Setting the build command to `hugo` will build your site according to the current default Hugo version used by Netlify. You can see the full list of [available Hugo versions in Netlify's Docker file][hugoversions]. -If you want to tell Netlify to build with a specific version, you can append an underscore followed by the version number to the build command: +If you want to tell Netlify to build with a specific version (hugo <= 0.20), you can append an underscore followed by the version number to the build command: ``` hugo_0.19 @@ -73,6 +73,22 @@ Your simple configuration should now look similar to the following:  +For version hugo > 0.20 you have to [specify version hugo for testing and production](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console. + +For production: + +``` +[context.production.environment] + HUGO_VERSION = "0.26" +``` + +For testing: + +``` +[context.deploy-preview.environment] + HUGO_VERSION = "0.26" +``` + Selecting "Deploy site" will immediately take you to a terminal for your build:.  diff --git a/docs/content/news/http2-server-push-in-hugo.md b/docs/content/news/http2-server-push-in-hugo.md index 76c39094e..369d0b221 100644 --- a/docs/content/news/http2-server-push-in-hugo.md +++ b/docs/content/news/http2-server-push-in-hugo.md @@ -66,7 +66,7 @@ Also note that this is a template for the home page, so the full `Page` with its ## 3. Add Template For the _redirects File -Add `layouts/index.redirects`: +Add `layouts/index.redir`: |