From 6a1a038c57b4084718743112e8fbb8bc6ea72f0a Mon Sep 17 00:00:00 2001 From: spf13 Date: Sat, 3 Aug 2013 03:31:25 -0400 Subject: [PATCH] Shrinking the readme to just the basics to avoid dupe with doc site --- README.md | 523 ++---------------------------------------------------- 1 file changed, 14 insertions(+), 509 deletions(-) diff --git a/README.md b/README.md index ae67cbc42..58f48599b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Hugo - -A really fast static site generator written in GoLang. +A Fast and Flexible Static Site Generator built with love by [spf13](http://spf13.com) +and [friends](http://github.com/spf13/hugo/contributors) in Go. ## Overview @@ -11,9 +11,13 @@ templates and renders them into a full html website. Hugo makes use of markdown files with front matter for meta data. A typical website of moderate size can be -rendered in a fraction of a second. It is written to work well with any +rendered in a fraction of a second. A good rule of thumb is that Hugo +takes around 1 millisecond for each piece of content. + +It is written to work well with any kind of website including blogs, tumbles and docs. +**Complete documentation is available at [Hugo Documentation](http://hugo.spf13.com).** # Getting Started @@ -36,7 +40,7 @@ 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. -*the Hugo executible has no external dependencies.* +*The Hugo executible has no external dependencies.* ### Installing from source @@ -61,519 +65,20 @@ it's helpful to symlink the project to one of the following paths: #### Get directly from Github: -If you don't intend to contribute, it's even easier. +If you only want to build from source, it's even easier. go get github.com/spf13/hugo -#### Running Hugo - - cd /path/to/hugo - go install github.com/spf13/hugo/hugolibs - go run main.go - #### Building Hugo cd /path/to/hugo go build -o hugo main.go mv hugo /usr/local/bin/ -## Source Directory Organization +#### Running Hugo -Hugo takes a single directory and uses it as the input for creating a complete website. + cd /path/to/hugo + go install github.com/spf13/hugo/hugolibs + go run main.go -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 - └── static - -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) - -d, --destination="": filesystem path to write files to - -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 - in 8 ms - -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 - in 8 ms - 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.8.0** August 1, 2013 - * Added support for pretty urls (filename/index.html vs filename.html) - * Hugo supports a destination directory - * Will efficiently sync content in static to destination directory - * Cleaned up options.. now with support for short and long options - * Added support for TOML - * Added support for YAML - * Added support for Previous & Next - * Support for Series - * Adding verbose output - * Loads of bugfixes -* **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 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). +**Complete documentation is available at [Hugo Documentation](http://hugo.spf13.com).**