From c1437ea45930a5829359db0d8ad69c4a16e2acbc Mon Sep 17 00:00:00 2001 From: Ryan Watters Date: Thu, 9 Mar 2017 19:08:32 -0600 Subject: [PATCH] Add finalized views.md and usage.md --- .../getting-started/directory-structure.md | 4 +- content/getting-started/installing.md | 17 ++- content/getting-started/usage.md | 117 +++++++----------- .../{content-view-templates.md => views.md} | 48 +++---- layouts/partials/style-embed.html | 2 +- pipeline/scss/components/_site-search.scss | 17 ++- .../scss/components/_table-of-contents.scss | 1 + static/css/style.min.css | 2 +- 8 files changed, 82 insertions(+), 126 deletions(-) rename content/templates/{content-view-templates.md => views.md} (59%) diff --git a/content/getting-started/directory-structure.md b/content/getting-started/directory-structure.md index 2e94f1c92..06758f6a2 100644 --- a/content/getting-started/directory-structure.md +++ b/content/getting-started/directory-structure.md @@ -19,8 +19,6 @@ website. ## Directory Scaffolding in `new hugo site` - - The top level of a source directory will typically have the following elements: ```bash @@ -34,7 +32,7 @@ The top level of a source directory will typically have the following elements: config.toml ``` -Learn more about the different directories and what their purpose is: +You can learn more about each component of a newly scaffolded site in its respective documentation: * [config](/getting-started/configuration/) * [data](/templates/data-templates/) diff --git a/content/getting-started/installing.md b/content/getting-started/installing.md index 9021d6be9..03822e9be 100644 --- a/content/getting-started/installing.md +++ b/content/getting-started/installing.md @@ -14,11 +14,7 @@ aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overv toc: true --- -## Quick Install - -Hugo is written in [Golang](https://golang.org/) with support for multiple platforms. - -The latest release can be found at [Hugo Releases][releases]. +Hugo is written in [Golang](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases]. Hugo currently provides pre-built binaries for the following: @@ -29,6 +25,8 @@ Hugo currently provides pre-built binaries for the following: Hugo may also be compiled from source wherever the Go compiler tool chain can run; e.g., for other operating systems, including DragonFly BSD, OpenBSD, Plan 9 and Solaris. See for the full set of supported combinations of target operating systems and compilation architectures. +## Quick Install + ### Binary (Cross-platform) Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account. @@ -45,7 +43,7 @@ brew update && brew install hugo ``` {{% /code %}} -For more detailed explanations, read the installation guides that follow for [Windows](#installing-hugo-on-windows) and [Mac OS X](#installing-hugo-on-mac-osx). +For more detailed explanations, read the installation guides that follow for installing on Mac OS X and Windows. ### Source @@ -72,7 +70,7 @@ You may run `go get` with the `-u` option to update Hugo's dependencies: go get -u -v github.com/spf13/hugo ``` -## OS X +## OS X ### Assumptions @@ -293,7 +291,7 @@ go build -o hugo main.go Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo. -## Windows +## Windows The following aims to be a complete guide to installing Hugo on your Windows PC. @@ -408,7 +406,7 @@ C:\Hugo\Sites\example.com>dir {{< youtube c8fJIRNChmU >}} -## Linux +## Linux ### Installing From Snap @@ -426,7 +424,6 @@ Install Hugo from the [Arch user repository](https://aur.archlinux.org/) on Arch Be aware that Hugo is built from source. This means that additional tools like Git and Go (the programming language Hugo is written in) will be installed as well. {{% /note %}} - ```bash sudo pacman -S yaourt yaourt -S hugo diff --git a/content/getting-started/usage.md b/content/getting-started/usage.md index e0a7760ae..f64c80c73 100644 --- a/content/getting-started/usage.md +++ b/content/getting-started/usage.md @@ -9,11 +9,12 @@ categories: [getting started] tags: [usage,livereload,command line,flags] weight: 40 draft: false -aliases: [/overview/usage/,/extras/livereload/,/doc/usage/] +aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/] toc: true -wip: true --- +The following is a description of the most command commands you will use while developing your Hugo project. See the [Command Line Reference][commands] for a comprehensive view of Hugo's CLI. + ## Testing Installation Once you have [installed Hugo][install], make sure it is in your `PATH`. You can test that Hugo has been installed correctly via the `help` command: @@ -88,11 +89,13 @@ Flags: -w, --watch watch filesystem for changes and recreate as needed ``` -## Common Usage +## The `hugo` Command The most common usage is probably to run `hugo` with your current directory being the input directory. -This generates your website to the `public/` directory by default, although you can customize the output directory in your [site configuration][config] by changing the `publishDir` field. The site Hugo renders into `public/` is ready to be deployed to your web server. +This generates your website to the `public/` directory by default, although you can customize the output directory in your [site configuration][config] by changing the `publishDir` field. + +The site Hugo renders into `public/` is ready to be deployed to your web server: ```bash hugo @@ -105,60 +108,46 @@ hugo in 90 ms ``` -## Instant Feedback During Development +## Draft, Future, and Expired Content -If you are working on things and want to see the changes immediately, by default Hugo will watch the file system for changes and rebuild your site as soon as a file is saved: +Hugo allows you to set `draft`, `publishdate`, and even `expirydate` in your content's [front matter][]. By default, Hugo will not publish: -```bash -hugo -s ~/Code/hugo/docs -0 draft content -0 future content -99 pages created -0 paginator pages created -16 tags created -0 groups created -in 120 ms -Watching for changes in /Users/spf13/Code/hugo/docs/content -Press Ctrl+C to stop -``` +1. Content with a future `publishdate` value +2. Content with `draft: true` status +3. Content with a past `expirydate` value -Hugo can even run a server and create a site preview at the same time! Hugo implements LiveReload technology to automatically reload any open pages in all JavaScript-enabled browsers, including mobile. This is the easiest and most common way to develop a Hugo web site: +All three of these can be overridden during both local development *and* deployment by adding the following flags to `hugo` and `hugo server`, respectively, or by changing the boolean values assigned to the fields of the same name (without `--`) in your [configuration][config]: -```bash -hugo server -ws ~/Code/hugo/docs -0 draft content -0 future content -99 pages created -0 paginator pages created -16 tags created -0 groups created -in 120 ms -Watching for changes in /Users/spf13/Code/hugo/docs/content -Serving pages from /Users/spf13/Code/hugo/docs/public -Web Server is available at http://localhost:1313/ -Press Ctrl+C to stop -``` -Hugo may not be the first static site generator to utilize LiveReload -technology, but it’s the first to do it right. +1. `--buildFuture` +2. `--buildDrafts` +3. `--buildExpired` -The combination of Hugo’s insane build speed and LiveReload make -crafting your content pure joy. Your updated content appears virtually instantly in your browser as soon as you save your changes. +## LiveReload -### LiveReload - -Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server and watch for changes: +Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server with the `hugo server` command and watch for changes: ```bash hugo server +0 draft content +0 future content +99 pages created +0 paginator pages created +16 tags created +0 groups created +in 120 ms +Watching for changes in /Users/yourname/sites/yourhugosite/{data,content,layouts,static} +Serving pages from /Users/yourname/sites/yourhugosite/public +Web Server is available at http://localhost:1313/ +Press Ctrl+C to stop ``` -This will run a fully functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following the following areas of your [project organization][dirs] +This will run a fully functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following areas of your [project organization][dirs]: * `/static/*` * `/content/*` * `/data/*` * `/layouts/*` -* `/themes//*` +* `/themes//*` * `config` Whenever you make changes, Hugo will simultaneously rebuild the site and continue to serve content. As soon as the build is finished, LiveReload tells the browser to silently reload the page. @@ -166,26 +155,26 @@ Whenever you make changes, Hugo will simultaneously rebuild the site and continu Most Hugo builds are so fast that you may not notice the change unless looking directly at the site in your browser. This means that keeping the site open on a second monitor (or another half of your current monitor) allows you to see the most up-to-date version of your website without the need to leave your text editor. {{% note "Closing `` Tag"%}} -You must have a closing `` tag for LiveReload to work. -Hugo injects the LiveReload `