From 16b1f284cae7abda49c951394c2284a2dba306ed Mon Sep 17 00:00:00 2001 From: spf13 Date: Wed, 24 Jul 2013 11:43:23 -0400 Subject: [PATCH] Improving installation instructions --- README.md | 37 +-- docs/content/doc/installing.md | 526 ++++++++++++++++++++++++++++++++- 2 files changed, 533 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 8e4085d3..4df41135 100644 --- a/README.md +++ b/README.md @@ -25,55 +25,56 @@ The latest release can be found at [hugo releases](https://github.com/spf13/hugo We currently build for Windows, Linux, FreeBSD and OS X for x64 and 386 architectures. +## Installing Hugo (binary) + Installation is very easy. Simply download the appropriate version for your -platform. Once downloaded it can be run from anywhere. You don't need to install +platform from [hugo releases](https://github.com/spf13/hugo/releases). +Once downloaded it 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. -Ideally you should install it somewhere in your path for easy use. `/usr/local/bin` +Ideally you should install it somewhere in your path for easy use. `/usr/local/bin` is the most probable location. -*Hugo has no external dependencies.* +*the Hugo executible has no external dependencies.* ## Installing from source -<<<<<<< HEAD ### Dependencies -Make sure you have a recent version of go installed. Hugo requires go 1.1+. - -**Due to packaging dependencies the following are also required: Git, Bazaar, Mercurial** - -### Cloning and Installing dependencies - -Pre-requisites: - * Git * Go 1.1+ * Mercurial * Bazaar -### Getting locally (for contributors): +### Clone locally (for contributors): - # clone and build git clone https://github.com/spf13/hugo cd hugo go get -### Install directly from Github: +Because go expects all of your libraries to be found in either $GOROOT or $GOPATH, +it's helpful to symlink the project to one of the following paths: + + * ln -s /path/to/your/hugo $GOPATH/src/github.com/spf13/hugo + * ln -s /path/to/your/hugo $GOROOT/src/pkg/github.com/spf13/hugo + +### Get directly from Github: + +If you don't intend to contribute, it's even easier. go get github.com/spf13/hugo - go build -o hugo main.go ### Running Hugo - cd hugo + cd /path/to/hugo go run main.go ### Building Hugo - cd hugo + cd /path/to/hugo go build -o hugo main.go + mv hugo /usr/local/bin/ ## Source Directory Organization diff --git a/docs/content/doc/installing.md b/docs/content/doc/installing.md index 5455cc35..c5d5924b 100644 --- a/docs/content/doc/installing.md +++ b/docs/content/doc/installing.md @@ -9,40 +9,542 @@ The latest release can be found at [hugo releases](https://github.com/spf13/hugo We currently build for Windows, Linux, FreeBSD and OS X for x64 and 386 architectures. +## Installing Hugo (binary) + Installation is very easy. Simply download the appropriate version for your -platform. Once downloaded it can be run from anywhere. You don't need to install +platform from [hugo releases](https://github.com/spf13/hugo/releases). +Once downloaded it 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. Ideally you should install it somewhere in your path for easy use. `/usr/local/bin` is the most probable location. -*Hugo has no external dependencies.* - -Installation is very easy. Simply download the appropriate version for your -platform. +*the Hugo executible has no external dependencies.* ## Installing from source ### Dependencies -Make sure you have a recent version of go installed. Hugo requires go 1.1+. +* Git +* Go 1.1+ +* Mercurial +* Bazaar -**Due to packaging dependencies the following are also required: Git, Bazaar, Mercurial** - -### Cloning and Installing dependencies +### Clone locally (for contributors): git clone https://github.com/spf13/hugo cd hugo go get - go build -o hugo main.go + +Because go expects all of your libraries to be found in either $GOROOT or $GOPATH, +it's helpful to symlink the project to one of the following paths: + + * ln -s /path/to/your/hugo $GOPATH/src/github.com/spf13/hugo + * ln -s /path/to/your/hugo $GOROOT/src/pkg/github.com/spf13/hugo + +### Get directly from Github: + +If you don't intend to contribute, it's even easier. + + go get github.com/spf13/hugo ### Running Hugo - cd hugo + cd /path/to/hugo go run main.go ### Building Hugo - cd hugo + cd /path/to/hugo go build -o hugo main.go + mv hugo /usr/local/bin/ + +## Source Directory Organization + +Hugo takes a single directory and uses it as the input for creating a complete website. + +Hugo has a very small amount of configuration, while remaining highly customizable. +It accomplishes by assuming that you will only provide templates with the intent of +using them. + +An example directory may look like: + + . + ├── config.json + ├── content + | ├── post + | | ├── firstpost.md + | | └── secondpost.md + | └── quote + | | ├── first.md + | | └── second.md + ├── layouts + | ├── chrome + | | ├── header.html + | | └── footer.html + | ├── indexes + | | ├── category.html + | | ├── post.html + | | ├── quote.html + | | └── tag.html + | ├── post + | | ├── li.html + | | ├── single.html + | | └── summary.html + | ├── quote + | | ├── li.html + | | ├── single.html + | | └── summary.html + | ├── shortcodes + | | ├── img.html + | | ├── vimeo.html + | | └── youtube.html + | ├── index.html + | └── rss.xml + └── public + +This directory structure tells us a lot about this site: + +1. the website intends to have two different types of content, posts and quotes. +2. It will also apply two different indexes to that content, categories and tags. +3. It will be displaying content in 3 different views, a list, a summary and a full page view. + +Included with the repository is an example site ready to be rendered. + +## Configuration + +The directory structure and templates provide the majority of the +configuration for a site. In fact a config file isn't even needed for many websites +since the defaults used follow commonly used patterns. + +**Please note the field names must be all lowercase** + +### Config Examples + +The following is an example of a yaml config file with the default values: + + --- + sourcedir: "content" + layoutdir: "layouts" + publishdir: "public" + builddrafts: false + indexes: + category: "categories" + tag: "tags" + baseurl: "http://yoursite.com/" + ... + + +The following is an example of a json config file with the default values: + + { + "sourcedir": "content", + "layoutdir": "layouts", + "publishdir": "public", + "builddrafts": false, + "indexes": { + category: "categories", + tag: "tags" + }, + "baseurl": "http://yoursite.com/" + } + + +The following is an example of a toml config file with the default values: + + sourcedir = "content" + layoutdir = "layouts" + publishdir = "public" + builddrafts = false + baseurl = "http://yoursite.com/" + [indexes] + category = "categories" + tag = "tags" + + +## Usage +Make sure either hugo is in your path or provide a path to it. + + $ hugo --help + usage: hugo [flags] [] + -b, --base-url="": hostname (and path) to the root eg. http://spf13.com/ + -d, --build-drafts=false: include content marked as draft + --config="": config file (default is path/config.yaml|json|toml) + -h, --help=false: show this help + --port="1313": port to run web server on, default :1313 + -S, --server=false: run a (very) simple web server + -s, --source="": filesystem path to read files relative from + --uglyurls=false: use /filename.html instead of /filename/ + -v, --verbose=false: verbose output + --version=false: which version of hugo + -w, --watch=false: watch filesystem for changes and recreate as needed + +The most common use is probably to run hugo with your current +directory being the input directory. + + + $ hugo + > X pages created + > Y indexes created + + +If you are working on things and want to see the changes +immediately, tell Hugo to watch for changes. **It will +recreate the site faster than you can tab over to +your browser to view the changes.** + + $ hugo --source ~/mysite --watch + Watching for changes. Press ctrl+c to stop + 15 pages created + 0 tags created + +Hugo can even run a server and create your site at the same time! + + $hugo --server -ws ~/mysite + Watching for changes. Press ctrl+c to stop + 15 pages created + 0 tags created + Web Server is available at http://localhost:1313 + Press ctrl+c to stop + +# Layout + +Hugo is very flexible about how you organize and structure your content. + +## Templates + +Hugo uses the excellent golang html/template library for it's template engine. It is an extremely +lightweight engine that provides a very small amount of logic. In our +experience that it is just the right amount of logic to be able to create a good static website + +This document will not cover how to use golang templates, but the [golang docs](http://golang.org/pkg/html/template/) +provide a good introduction. + +### Template roles + +There are 5 different kinds of templates that Hugo works with. + +#### index.html +This file must exist in the layouts directory. It is the template used to render the +homepage of your site. + +#### rss.xml +This file must exist in the layouts directory. It will be used to render all rss documents. +The one provided in the example application will generate an ATOM format. + +*Important: Hugo will automatically add the following header line to this file.* + + + +#### Indexes +An index is a page that list multiple pieces of content. If you think of a typical blog, the tag +pages are good examples of indexes. + + +#### Content Type(s) +Hugo supports multiple types of content. Another way of looking at this is that Hugo has the ability +to render content in a variety of ways as determined by the type. + +#### Chrome +Chrome is simply the decoration of your site. It's not a requirement to have this, but in practice +it's very convenient. Hugo doesn't know anything about Chrome, it's simply a convention that you may +likely find beneficial. As you create the rest of your templates you will include templates from the +/layout/chrome directory. I've found it helpful to include a header and footer template +in Chrome so I can include those in the other full page layouts (index.html, indexes/ type/single.html). + +### Adding a new content type + +Adding a type is easy. + +**Step 1:** +Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*. + +**Step 2:** +Create a file called single.html inside your directory. *Eg /layouts/post/single.html*. + +**Step 3:** +Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/index/post.html*. + +**Step 4:** +Many sites support rendering content in a few different ways, for instance a single page view and a +summary view to be used when displaying a list of contents on a single page. Hugo makes no assumptions +here about how you want to display your content, and will support as many different views of a content +type as your site requires. All that is required for these additional views is that a template +exists in each layout/type directory with the same name. + +For these, reviewing the example site will be very helpful in order to understand how these types work. + +## Variables + +Hugo makes a set of values available to the templates. Go templates are context based. The following +are available in the context for the templates. + +**.Title** The title for the content.
+**.Description** The description for the content.
+**.Keywords** The meta keywords for this content.
+**.Date** The date the content is published on.
+**.Indexes** These will use the field name of the plural form of the index (see tags and categories above)
+**.Permalink** The Permanent link for this page.
+**.FuzzyWordCount** The approximate number of words in the content.
+**.RSSLink** Link to the indexes' rss link
+ +Any value defined in the front matter, including indexes will be made available under `.Params`. +Take for example I'm using tags and categories as my indexes. The following would be how I would access them: + +**.Params.Tags**
+**.Params.Categories**
+ +Also available is `.Site` which has the following: + +**.Site.BaseUrl** The base URL for the site as defined in the config.json file.
+**.Site.Indexes** The names of the indexes of the site.
+**.Site.LastChange** The date of the last change of the most recent content.
+**.Site.Recent** Array of all content ordered by Date, newest first
+ +# Content +Hugo uses markdown files with headers commonly called the front matter. Hugo respects the organization +that you provide for your content to minimize any extra configuration, though this can be overridden +by additional configuration in the front matter. + +## Organization +In Hugo the content should be arranged in the same way they are intended for the rendered website. +Without any additional configuration the following will just work. + + . + └── content + ├── post + | ├── firstpost.md // <- http://site.com/post/firstpost.html + | └── secondpost.md // <- http://site.com/post/secondpost.html + └── quote + ├── first.md // <- http://site.com/quote/first.html + └── second.md // <- http://site.com/quote/second.html + + +## Front Matter + +The front matter is one of the features that gives Hugo it's strength. It enables +you to include the meta data of the content right with it. Hugo supports a few +different formats each with their own identifying tokens. + +Supported formats:
+ **YAML**, identified by '\-\-\-'.
+ **TOML**, indentified with '+++'.
+ **JSON**, a single JSON object which is surrounded by '{' and '}' each on their own line. + +### YAML Example + + --- + title: "spf13-vim 3.0 release and new website" + description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." + tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ] + pubdate: "2012-04-06" + categories: + - "Development" + - "VIM" + slug: "spf13-vim-3-0-release-and-new-website" + --- + Content of the file goes Here + +### TOML Example + + +++ + title = "spf13-vim 3.0 release and new website" + description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." + tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] + Pubdate = "2012-04-06" + categories = [ + "Development", + "VIM" + ] + slug = "spf13-vim-3-0-release-and-new-website" + +++ + Content of the file goes Here + +### JSON Example + + { + "title": "spf13-vim 3.0 release and new website", + "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.", + "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ], + "date": "2012-04-06", + "categories": [ + "Development", + "VIM" + ], + "slug": "spf13-vim-3-0-release-and-new-website", + } + Content of the file goes Here + +### Variables +There are a few predefined variables that Hugo is aware of and utilizes. The user can also create +any variable they want to. These will be placed into the `.Params` variable available to the templates. +**Field names are case insensitive.** + +#### Required + +**title** The title for the content.
+**description** The description for the content.
+**date** The date the content will be sorted by.
+**indexes** These will use the field name of the plural form of the index (see tags and categories above) + +#### Optional + +**draft** If true the content will not be rendered unless `hugo` is called with -d
+**type** The type of the content (will be derived from the directory automatically if unset).
+**markup** (Experimental) Specify "rst" for reStructuredText (requires + `rst2html`,) or "md" (default) for the Markdown.
+**slug** The token to appear in the tail of the url.
+ *or*
+**url** The full path to the content from the web root.
+*If neither is present the filename will be used.* + +## Example +Somethings are better shown than explained. The following is a very basic example of a content file: + +**mysite/project/nitro.md <- http://mysite.com/project/nitro.html** + + --- + Title: "Nitro : A quick and simple profiler for golang" + Description": "" + Keywords": [ "Development", "golang", "profiling" ] + Tags": [ "Development", "golang", "profiling" ] + Pubdate": "2013-06-19" + Topics": [ "Development", "GoLang" ] + Slug": "nitro" + project_url": "http://github.com/spf13/nitro" + --- + + # Nitro + + Quick and easy performance analyzer library for golang. + + ## Overview + + Nitro is a quick and easy performance analyzer library for golang. + It is useful for comparing A/B against different drafts of functions + or different functions. + + ## Implementing Nitro + + Using Nitro is simple. First use go get to install the latest version + of the library. + + $ go get github.com/spf13/nitro + + Next include nitro in your application. + + +# Extras + +## Shortcodes +Because Hugo uses markdown for it's content format, it was clear that there's a lot of things that +markdown doesn't support well. This is good, the simple nature of markdown is exactly why we chose it. + +However we cannot accept being constrained by our simple format. Also unacceptable is writing raw +html in our markdown every time we want to include unsupported content such as a video. To do +so is in complete opposition to the intent of using a bare bones format for our content and +utilizing templates to apply styling for display. + +To avoid both of these limitations Hugo has full support for shortcodes. + +### What is a shortcode? +A shortcode is a simple snippet inside a markdown file that Hugo will render using a template. + +Short codes are designated by the opening and closing characters of '{{%' and '%}}' respectively. +Short codes are space delimited. The first word is always the name of the shortcode. Following the +name are the parameters. The author of the shortcode can choose if the short code +will use positional parameters or named parameters (but not both). A good rule of thumb is that if a +short code has a single required value in the case of the youtube example below then positional +works very well. For more complex layouts with optional parameters named parameters work best. + +The format for named parameters models that of html with the format name="value" + +### Example: youtube + + {{% youtube 09jf3ow9jfw %}} + +This would be rendered as + +
+ +
+ +### Example: image with caption + + {{% img src="/media/spf13.jpg" title="Steve Francia" %}} + +Would be rendered as: + +
+ +
+

Steve Francia

+
+
+ + +### Creating a shortcode + +All that you need to do to create a shortcode is place a template in the layouts/shortcodes directory. + +The template name will be the name of the shortcode. + +**Inside the template** + +To access a parameter by either position or name the index method can be used. + + {{ index .Params 0 }} + or + {{ index .Params "class" }} + +To check if a parameter has been provided use the isset method provided by Hugo. + + {{ if isset .Params "class"}} class="{{ index .Params "class"}}" {{ end }} + + +# Meta + +## Release Notes + +* **0.7.0** July 4, 2013 + * Hugo now includes a simple server + * First public release +* **0.6.0** July 2, 2013 + * Hugo includes an [example documentation site](http://hugo.spf13.com) which it builds +* **0.5.0** June 25, 2013 + * Hugo is quite usable and able to build [spf13.com](http://spf13.com) + +## Roadmap +In no particular order, here is what I'm working on: + + * Pagination + * Support for top level pages (other than homepage) + * Series support + * Syntax highlighting + * Previous & Next + * Related Posts + * Support for TOML front matter -- in head + * Proper YAML support for front matter -- in head + * Support for other formats + +## Contributing + +1. Fork it +2. Create your feature branch (`git checkout -b my-new-feature`) +3. Commit your changes (`git commit -am 'Add some feature'`) +4. Push to the branch (`git push origin my-new-feature`) +5. Create new Pull Request + +## Contributors + +* [spf13](https://github.com/spf13) + + +## License + +Hugo is released under the Simple Public License. See [LICENSE.md](https://github.com/spf13/hugo/blob/master/LICENSE.md). -- 2.30.2