diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 129 |
1 files changed, 103 insertions, 26 deletions
@@ -1,45 +1,122 @@ -# Hugo Docs + -Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in Go. +A Fast and Flexible Static Site Generator built with love by [bep](https://github.com/bep), [spf13](http://spf13.com/) and [friends](https://github.com/gohugoio/hugo/graphs/contributors) in [Go][]. -## Contributing +[Website](https://gohugo.io) | +[Forum](https://discourse.gohugo.io) | +[Developer Chat (no support)](https://gitter.im/gohugoio/hugo) | +[Documentation](https://gohugo.io/overview/introduction/) | +[Installation Guide](https://gohugo.io/overview/installing/) | +[Contribution Guide](CONTRIBUTING.md) | +[Twitter](https://twitter.com/gohugoio) -We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you. +[](https://godoc.org/github.com/gohugoio/hugo) +[](https://travis-ci.org/gohugoio/hugo) +[](https://ci.appveyor.com/project/bep/hugo/branch/master) +[](https://gitter.im/spf13/hugo?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +[](https://goreportcard.com/report/github.com/gohugoio/hugo) -Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository. +## Overview -*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.* +Hugo is a static HTML and CSS website generator written in [Go][]. +It is optimized for speed, ease of use, and configurability. +Hugo takes a directory with content and templates and renders them into a full HTML website. -Spelling fixes are most welcomed, and if you want to contribute longer sections to the documentation, it would be great if you had these in mind when writing: +Hugo relies on Markdown files with front matter for metadata, and you can run Hugo from any directory. +This works well for shared hosts and other systems where you don’t have a privileged account. -* Short is good. People go to the library to read novels. If there is more than one way to _do a thing_ in Hugo, describe the current _best practice_ (avoid "… but you can also do …" and "… in older versions of Hugo you had to …". -* For examples, try to find short snippets that teaches people about the concept. If the example is also useful as-is (copy and paste), then great, but don't list long and similar examples just so people can use them on their sites. -* Hugo has users from all over the world, so an easy to understand and [simple English](https://simple.wikipedia.org/wiki/Basic_English) is good. +Hugo renders a typical website of moderate size in a fraction of a second. +A good rule of thumb is that each piece of content renders in around 1 millisecond. -## Branches +Hugo is designed to work well for any kind of website including blogs, tumbles, and docs. -* The `master` branch is where the site is automatically built from, and is the place to put changes relevant to the current Hugo version. -* The `next` branch is where we store changes that is related to the next Hugo release. This can be previewed here: https://next--gohugoio.netlify.com/ +#### Supported Architectures -## Build +Currently, we provide pre-built Hugo binaries for Windows, Linux, FreeBSD, NetBSD, macOS (Darwin), and [Android](https://gist.github.com/bep/a0d8a26cf6b4f8bc992729b8e50b480b) for x64, i386 and ARM architectures. -To view the documentation site locally, you need to clone this repository: +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. + +**Complete documentation is available at [Hugo Documentation][].** + +## Choose How to Install + +If you want to use Hugo as your site generator, simply install the Hugo binaries. +The Hugo binaries have no external dependencies. + +To contribute to the Hugo source code or documentation, you should [fork the Hugo GitHub project](https://github.com/gohugoio/hugo#fork-destination-box) and clone it to your local machine. + +Finally, you can install the Hugo source code with `go`, build the binaries yourself, and run Hugo that way. +Building the binaries is an easy task for an experienced `go` getter. + +### Install Hugo as Your Site Generator (Binary Install) + +Use the [installation instructions in the Hugo documentation](https://gohugo.io/overview/installing/). + +### Build and Install the Binaries from Source (Advanced Install) + +#### Prerequisite Tools + +* [Git](https://git-scm.com/) +* [Go (at least Go 1.11)](https://golang.org/dl/) + +#### Fetch from GitHub + +Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest is is to clone Hugo in a directory outside of `GOPATH`, as in the following example: ```bash -git clone https://github.com/gohugoio/hugoDocs.git +mkdir $HOME/src +cd $HOME/src +git clone https://github.com/gohugoio/hugo.git +cd hugo +go install ``` -Also note that the documentation version for a given version of Hugo can also be found in the `/docs` sub-folder of the [Hugo source repository](https://github.com/gohugoio/hugo). +**If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`.** + +## The Hugo Documentation -Then to view the docs in your browser, run Hugo and open up the link: +The Hugo documentation now lives in its own repository, see https://github.com/gohugoio/hugoDocs. But we do keep a version of that documentation as a `git subtree` in this repository. To build the sub folder `/docs` as a Hugo site, you need to clone this repo: ```bash -▶ hugo server - -Started building sites ... -. -. -Serving pages from memory -Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) -Press Ctrl+C to stop +git clone git@github.com:gohugoio/hugo.git ``` +## Contributing to Hugo + +For a complete guide to contributing to Hugo, see the [Contribution Guide](CONTRIBUTING.md). + +We welcome contributions to Hugo of any kind including documentation, themes, +organization, tutorials, blog posts, bug reports, issues, feature requests, +feature implementations, pull requests, answering questions on the forum, +helping to manage issues, etc. + +The Hugo community and maintainers are [very active](https://github.com/gohugoio/hugo/pulse/monthly) and helpful, and the project benefits greatly from this activity. + +### Asking Support Questions + +We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions. +Please don't use the GitHub issue tracker to ask questions. + +### Reporting Issues + +If you believe you have found a defect in Hugo or its documentation, use +the GitHub issue tracker to report the problem to the Hugo maintainers. +If you're not sure if it's a bug or not, start by asking in the [discussion forum](https://discourse.gohugo.io). +When reporting the issue, please provide the version of Hugo in use (`hugo version`). + +### Submitting Patches + +The Hugo project welcomes all contributors and contributions regardless of skill or experience level. +If you are interested in helping with the project, we will help you with your contribution. +Hugo is a very active project with many contributions happening daily. + +Because we want to create the best possible product for our users and the best contribution experience for our developers, +we have a set of guidelines which ensure that all contributions are acceptable. +The guidelines are not intended as a filter or barrier to participation. +If you are unfamiliar with the contribution process, the Hugo team will help you and teach you how to bring your contribution in accordance with the guidelines. + +For a complete guide to contributing code to Hugo, see the [Contribution Guide](CONTRIBUTING.md). + +[](https://github.com/igrigorik/ga-beacon) + +[Go]: https://golang.org/ +[Hugo Documentation]: https://gohugo.io/overview/introduction/ |