diff options
author | spf13 <steve.francia@gmail.com> | 2013-07-04 11:32:55 -0400 |
---|---|---|
committer | spf13 <steve.francia@gmail.com> | 2013-07-04 11:32:55 -0400 |
commit | 6e16449e5fca5df192de04430af26a46ea9ceb2d (patch) | |
tree | efa5ce31f86a99b4a8f410fda0784dd4cc8f9a92 | |
parent | 50a1d6f3f155ab837310e00ffb309a9199773c73 (diff) |
adding hugo
34 files changed, 3458 insertions, 0 deletions
diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 000000000..f7c18741d --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,67 @@ +Simple Public License (SimPL-2.0) +================================= + +Preamble +-------- + +This Simple Public License 2.0 (SimPL-2.0 for short) is a plain language +implementation of GPL 2.0. The words are different, but the goal is the +same - to guarantee for all users the freedom to share and change +software. If anyone wonders about the meaning of the SimPL, they should +interpret it as consistent with GPL 2.0. + + +Simple Public License (SimPL) 2.0 +================================= + +The SimPL applies to the software's source and object code and comes +with any rights that I have in it (other than trademarks). You agree to +the SimPL by copying, distributing, or making a derivative work of the +software. + + You get the royalty free right to: + +- Use the software for any purpose; +- Make derivative works of it (this is called a "Derived Work"); +- Copy and distribute it and any Derived Work. + +If you distribute the software or a Derived Work, you must give back to +the community by: + +- Prominently noting the date of any changes you make; +- Leaving other people's copyright notices, warranty disclaimers, and + license terms in place; +- Providing the source code, build scripts, installation scripts, and + interface definitions in a form that is easy to get and best to + modify; +- Licensing it to everyone under SimPL, or substantially similar terms + (such as GPL 2.0), without adding further restrictions to the rights + provided; +- Conspicuously announcing that it is available under that license. + +There are some things that you must shoulder: + +- You get NO WARRANTIES. None of any kind; +- If the software damages you in any way, you may only recover direct + damages up to the amount you paid for it (that is zero if you did + not pay anything). You may not recover any other damages, including + those called "consequential damages." (The state or country where + you live may not allow you to limit your liability in this way, so + this may not apply to you); + +The SimPL continues perpetually, except that your license rights end +automatically if: + +- You do not abide by the "give back to the community" terms (your + licensees get to keep their rights if they abide); +- Anyone prevents you from distributing the software under the terms + of the SimPL. + +License for the License +----------------------- + +You may do anything that you want with the SimPL text; it's a license +form to use in any way that you find helpful. To avoid confusion, +however, if you change the terms in any way then you may not call your +license the Simple Public License or the SimPL (but feel free to +acknowledge that your license is "based on the Simple Public License"). diff --git a/docs/config.json b/docs/config.json new file mode 100644 index 000000000..6c8a198d8 --- /dev/null +++ b/docs/config.json @@ -0,0 +1,4 @@ +{ + "Indexes" : {"tag": "tags"}, + "BaseUrl" : "http://localhost" +} diff --git a/docs/content/doc/configuration.md b/docs/content/doc/configuration.md new file mode 100644 index 000000000..bc8df19e0 --- /dev/null +++ b/docs/content/doc/configuration.md @@ -0,0 +1,19 @@ +{ + "title": "Configuring Hugo", + "Pubdate": "2013-07-01" +} + +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. + +The following is an example of a config file with the default values + + { + "SourceDir" : "content", + "LayoutDir" : "layouts", + "PublishDir" : "public", + "BuildDrafts" : false, + "Tags" : { "category" : "categories", "tag" : "tags" }, + "BaseUrl" : "http://yourSite.com/" + } diff --git a/docs/content/doc/contributing.md b/docs/content/doc/contributing.md new file mode 100644 index 000000000..8ff4fccb4 --- /dev/null +++ b/docs/content/doc/contributing.md @@ -0,0 +1,10 @@ +{ + "title": "Contributing to Hugo", + "Pubdate": "2013-07-01" +} + +1. Fork it from https://github.com/spf13/hugo +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 diff --git a/docs/content/doc/contributors.md b/docs/content/doc/contributors.md new file mode 100644 index 000000000..003d18553 --- /dev/null +++ b/docs/content/doc/contributors.md @@ -0,0 +1,9 @@ +{ + "title": "Contributors", + "Pubdate": "2013-07-01" +} + +Hugo was built with love and golang by: + +* [spf13](https://github.com/spf13) + diff --git a/docs/content/doc/example.md b/docs/content/doc/example.md new file mode 100644 index 000000000..67311a1ca --- /dev/null +++ b/docs/content/doc/example.md @@ -0,0 +1,40 @@ +{ + "title": "Example Content File", + "Pubdate": "2013-07-01" +} + +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. + + diff --git a/docs/content/doc/front-matter.md b/docs/content/doc/front-matter.md new file mode 100644 index 000000000..6feb74e4e --- /dev/null +++ b/docs/content/doc/front-matter.md @@ -0,0 +1,38 @@ +{ + "title": "Front Matter", + "Pubdate": "2013-07-01" +} + +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. The main format supported is JSON. Here is an 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" + } + +### 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. + +#### Required + +**Title** The title for the content. <br> +**Description** The description for the content.<br> +**Pubdate** The date the content will be sorted by.<br> +**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<br> +**Type** The type of the content (will be derived from the directory automatically if unset).<br> +**Slug** The token to appear in the tail of the url.<br> + *or*<br> +**Url** The full path to the content from the web root.<br> +*If neither is present the filename will be used.* + diff --git a/docs/content/doc/installing.md b/docs/content/doc/installing.md new file mode 100644 index 000000000..aa061ffdf --- /dev/null +++ b/docs/content/doc/installing.md @@ -0,0 +1,18 @@ +{ + "title": "Installing Hugo", + "Pubdate": "2013-07-01" +} + +Installation is very easy. Simply download the appropriate version for your +platform. + +Hugo is written in GoLang with support for Windows, Linux and OSX. + +<div class="alert alert-info"> +Please make sure that you place the executable in your path. `/usr/local/bin` +is the most probable location. +</div> + + +Hugo doesn't have any external dependencies, but can benefit from external +programs. diff --git a/docs/content/doc/license.md b/docs/content/doc/license.md new file mode 100644 index 000000000..257c4cf93 --- /dev/null +++ b/docs/content/doc/license.md @@ -0,0 +1,75 @@ +{ + "title": "License", + "Pubdate": "2013-07-01" +} + +Hugo is released under the Simple Public License. + + +Simple Public License (SimPL-2.0) +================================= + +Preamble +-------- + +This Simple Public License 2.0 (SimPL-2.0 for short) is a plain language +implementation of GPL 2.0. The words are different, but the goal is the +same - to guarantee for all users the freedom to share and change +software. If anyone wonders about the meaning of the SimPL, they should +interpret it as consistent with GPL 2.0. + + +Simple Public License (SimPL) 2.0 +================================= + +The SimPL applies to the software's source and object code and comes +with any rights that I have in it (other than trademarks). You agree to +the SimPL by copying, distributing, or making a derivative work of the +software. + + You get the royalty free right to: + +- Use the software for any purpose; +- Make derivative works of it (this is called a "Derived Work"); +- Copy and distribute it and any Derived Work. + +If you distribute the software or a Derived Work, you must give back to +the community by: + +- Prominently noting the date of any changes you make; +- Leaving other people's copyright notices, warranty disclaimers, and + license terms in place; +- Providing the source code, build scripts, installation scripts, and + interface definitions in a form that is easy to get and best to + modify; +- Licensing it to everyone under SimPL, or substantially similar terms + (such as GPL 2.0), without adding further restrictions to the rights + provided; +- Conspicuously announcing that it is available under that license. + +There are some things that you must shoulder: + +- You get NO WARRANTIES. None of any kind; +- If the software damages you in any way, you may only recover direct + damages up to the amount you paid for it (that is zero if you did + not pay anything). You may not recover any other damages, including + those called "consequential damages." (The state or country where + you live may not allow you to limit your liability in this way, so + this may not apply to you); + +The SimPL continues perpetually, except that your license rights end +automatically if: + +- You do not abide by the "give back to the community" terms (your + licensees get to keep their rights if they abide); +- Anyone prevents you from distributing the software under the terms + of the SimPL. + +License for the License +----------------------- + +You may do anything that you want with the SimPL text; it's a license +form to use in any way that you find helpful. To avoid confusion, +however, if you change the terms in any way then you may not call your +license the Simple Public License or the SimPL (but feel free to +acknowledge that your license is "based on the Simple Public License"). diff --git a/docs/content/doc/organization.md b/docs/content/doc/organization.md new file mode 100644 index 000000000..49647c53e --- /dev/null +++ b/docs/content/doc/organization.md @@ -0,0 +1,22 @@ +{ + "title": "Organization", + "Pubdate": "2013-07-01" +} + +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 + diff --git a/docs/content/doc/release-notes.md b/docs/content/doc/release-notes.md new file mode 100644 index 000000000..34bd53156 --- /dev/null +++ b/docs/content/doc/release-notes.md @@ -0,0 +1,14 @@ +{ + "title": "Release Notes", + "Pubdate": "2013-07-01" + +} + +* **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 which it builds +* **0.5.0** June 25, 2013 + * Hugo is quite usable and able to build spf13.com + diff --git a/docs/content/doc/roadmap.md b/docs/content/doc/roadmap.md new file mode 100644 index 000000000..3a4faf725 --- /dev/null +++ b/docs/content/doc/roadmap.md @@ -0,0 +1,18 @@ +{ + "title": "Roadmap", + "Pubdate": "2013-07-01" +} + +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 + * Proper YAML support for front matter + * Support for other formats + + diff --git a/docs/content/doc/shortcodes.md b/docs/content/doc/shortcodes.md new file mode 100644 index 000000000..1d30aa8dc --- /dev/null +++ b/docs/content/doc/shortcodes.md @@ -0,0 +1,76 @@ +{ + "title": "Shortcodes", + "Pubdate": "2013-07-01" +} + +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 +*Example has an extra space so Hugo doesn't actually render it* + + {{ % youtube 09jf3ow9jfw %}} + +This would be rendered as + + <div class="embed video-player"> + <iframe class="youtube-player" type="text/html" + width="640" height="385" + src="http://www.youtube.com/embed/09jf3ow9jfw" + allowfullscreen frameborder="0"> + </iframe> + </div> + +### Example: image with caption +*Example has an extra space so Hugo doesn't actually render it* + + {{ % img src="/media/spf13.jpg" title="Steve Francia" %}} + +Would be rendered as: + + <figure > + <img src="/media/spf13.jpg" /> + <figcaption> + <h4>Steve Francia</h4> + </figcaption> + </figure> + + +### 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 }} + + diff --git a/docs/content/doc/source-directory.md b/docs/content/doc/source-directory.md new file mode 100644 index 000000000..84a3dcc28 --- /dev/null +++ b/docs/content/doc/source-directory.md @@ -0,0 +1,54 @@ +{ + "title": "Source Directory Organization", + "Pubdate": "2013-07-01" +} + +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 this example site ready to be rendered. diff --git a/docs/content/doc/templates.md b/docs/content/doc/templates.md new file mode 100644 index 000000000..e7403bc56 --- /dev/null +++ b/docs/content/doc/templates.md @@ -0,0 +1,66 @@ +{ + "title": "Templates", + "Pubdate": "2013-07-01" +} + +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.* + + <?xml version="1.0" encoding="utf-8" standalone="yes" ?> + +#### Indexes |