diff options
Diffstat (limited to 'docs/content/en/getting-started/quick-start.md')
| -rw-r--r-- | docs/content/en/getting-started/quick-start.md | 244 |
1 files changed, 142 insertions, 102 deletions
diff --git a/docs/content/en/getting-started/quick-start.md b/docs/content/en/getting-started/quick-start.md index 4fbdb1c8f..829800048 100644 --- a/docs/content/en/getting-started/quick-start.md +++ b/docs/content/en/getting-started/quick-start.md @@ -1,176 +1,216 @@ --- title: Quick Start linktitle: Quick Start -description: Create a Hugo site using the beautiful Ananke theme. -date: 2013-07-01 -publishdate: 2013-07-01 +description: Learn to create a Hugo site in minutes. categories: [getting started] keywords: [quick start,usage] -authors: [Shekhar Gulati, Ryan Watters] menu: docs: - parent: "getting-started" + parent: getting-started weight: 10 weight: 10 -sections_weight: 10 -draft: false -aliases: [/quickstart/,/overview/quickstart/] toc: true +aliases: [/quickstart/,/overview/quickstart/] --- -{{% note %}} -This quick start uses `macOS` in the examples. For instructions about how to install Hugo on other operating systems, see [install](/installation/). +In this tutorial you will: -It is required to have [Git installed](https://git-scm.com/downloads) to run this tutorial. +1. Create a site +2. Add content +3. Configure the site +4. Publish the site -For other approaches to learning Hugo (like books or video tutorials), refer to the [external learning resources](/getting-started/external-learning-resources/) page. -{{% /note %}} +## Prerequisites -## Step 1: Install Hugo +Before you begin this tutorial you must: -Install the **extended version of Hugo** (this is required for the current theme used). +1. [Install Hugo] (the extended edition) +1. [Install Git] -{{% note %}} -`Homebrew` and `MacPorts`, package managers for `macOS`, can be installed from [brew.sh](https://brew.sh/) or [macports.org](https://www.macports.org/) respectively. See [install](/installation/) if you are running Windows etc. -{{% /note %}} +You must also be comfortable working from the command line. -```bash -brew install hugo -# or -port install hugo -``` +## Create a site + +### Commands + +Run these commands[^1] to create a Hugo site with the [Ananke] theme. The next section provides an explanation of each command. -To verify your new install: +[^1]: If you are a Windows user, you must run these commands with [PowerShell]. You cannot use Windows Powershell, which is a different application, or the Command Prompt. -```bash -hugo version -# Example output: hugo v0.104.2+extended darwin/amd64 BuildDate=unknown +```text +hugo new site quickstart +cd quickstart +git init +git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke +echo "theme = 'ananke'" >> config.toml +hugo server ``` -It should state that it is `extended`. If it does not, uninstall it and try another installation method. +View your site at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server. -{{< asciicast ItACREbFgvJ0HjnSNeTknxWy9 >}} +### Explanation of commands -## Step 2: Create a New Site +Create the [directory structure] for your project in the `quickstart` directory. -```bash +```text hugo new site quickstart ``` -The above will create a new Hugo site in a folder named `quickstart`. +Change the current directory to the root of your project. -{{< asciicast 3mf1JGaN0AX0Z7j5kLGl3hSh8 >}} +```text +cd quickstart +``` -## Step 3: Add a Theme +Initialize an empty Git repository in the current directory. -See [themes.gohugo.io](https://themes.gohugo.io/) for a list of themes to consider. This quickstart uses the beautiful [Ananke theme](https://themes.gohugo.io/gohugo-theme-ananke/). +```text +git init +``` -First, download the theme from GitHub and add it to your site's `themes` directory: +Clone the [Ananke] theme into the `themes` directory, adding it to your project as a [Git submodule]. -```bash -cd quickstart -git init -git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke +```text +git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke ``` -Then, add the theme to the site configuration: +Append a line to the site configuration file, indicating the current theme. -```bash -echo theme = \"ananke\" >> config.toml +```text +echo "theme = 'ananke'" >> config.toml ``` -{{< asciicast 7naKerRYUGVPj8kiDmdh5k5h9 >}} +Start Hugo's development server to view the site. -## Step 4: Add Some Content +```text +hugo server +``` + +Press `Ctrl + C` to stop Hugo's development server. + +## Add content -You can manually create content files (for example as `content/<CATEGORY>/<FILE>.<FORMAT>`) and provide metadata in them, however you can use the `new` command to do a few things for you (like add title and date): +Add a new page to your site. -```txt +```text hugo new posts/my-first-post.md ``` -{{< asciicast eUojYCfRTZvkEiqc52fUsJRBR >}} +Hugo created the file in the `content/posts` directory. Open the file with your editor. + +```text +--- +title: "My First Post" +date: 2022-11-20T09:03:20-08:00 +draft: true +--- +``` + +Notice the `draft` value in the [front matter] is `true`. By default, Hugo does not publish draft content when you build the site. Learn more about [draft, future, and expired content]. + +Add some [markdown] to the body of the post, but do not change the `draft` value. -Edit the newly created content file if you want, it will start with something like this: +[markdown]: https://commonmark.org/help/ -```md +```text --- title: "My First Post" -date: 2019-03-26T08:47:11+01:00 +date: 2022-11-20T09:03:20-08:00 draft: true --- +## Introduction +This is **bold** text, and this is *emphasized* text. + +Visit the [Hugo](https://gohugo.io) website! +``` + +Save the file, then start Hugo’s development server to view the site. You can run either of the following commands to include draft content. + +```text +hugo server --buildDrafts +hugo server -D ``` +View your site at the URL displayed in your terminal. Keep the development server running as you continue to add and change content. + {{% note %}} -Drafts do not get deployed; once you finish a post, update the header of the post to say `draft: false`. More info [here](/getting-started/usage/#draft-future-and-expired-content). +Hugo's rendering engine conforms to the CommonMark [specification] for markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation. + +[live testing tool]: https://spec.commonmark.org/dingus/ +[specification]: https://spec.commonmark.org/ {{% /note %}} -## Step 5: Start the Hugo server - -Now, start the Hugo server with [drafts](/getting-started/usage/#draft-future-and-expired-content) enabled: - -{{< asciicast BvJBsF6egk9c163bMsObhuNXj >}} - -```txt -▶ hugo server -D - - | EN -+------------------+----+ - Pages | 10 - Paginator pages | 0 - Non-page files | 0 - Static files | 3 - Processed images | 0 - Aliases | 1 - Sitemaps | 1 - Cleaned | 0 - -Total in 11 ms -Watching for changes in /Users/bep/quickstart/{content,data,layouts,static,themes} -Watching for config changes in /Users/bep/quickstart/config.toml -Environment: "development" -Serving pages from memory -Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender -Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) -Press Ctrl+C to stop -``` +## Configure the site -**Navigate to your new site at [http://localhost:1313/](http://localhost:1313/).** +With your editor, open the [site configuration] file (`config.toml`) in the root of your project. -Feel free to edit or add new content and you will see the changes in the browser right away while the Hugo server is running. (You might need to force refresh your web browser, something like Ctrl-R usually works.) +```text +baseURL = 'http://example.org/' +languageCode = 'en-us' +title = 'My New Hugo Site' +theme = 'ananke' +``` -## Step 6: Customize the Theme +Make the following changes: -Your new site already looks great, but you will want to tweak it a little before you release it to the public. +1. Set the `baseURL` for your production site. This value must begin with the protocol and end with a slash, as shown above. -### Site Configuration +2. Set the `languageCode` to your language and region. -Open up `config.toml` in a text editor: +3. Set the `title` for your production site. -```toml -baseURL = "https://example.org/" -languageCode = "en-us" -title = "My New Hugo Site" -theme = "ananke" -``` +Start Hugo's development server to see your changes, remembering to include draft content. -Replace the `title` above with something more personal. Also, if you already have a domain ready, set the `baseURL`. Note that this value is not needed when running the local development server. +```text +hugo server -D +``` {{% note %}} -**Tip:** Make the changes to the site configuration or any other file in your site while the Hugo server is running, and you will see the changes in the browser right away, though you may need to [clear your cache](https://kb.iu.edu/d/ahic). +Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details. + +[The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site]. + +[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/ +[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme +[The New Dynamic]: https://www.thenewdynamic.com/ {{% /note %}} -For theme specific configuration options, see the [theme site](https://github.com/theNewDynamic/gohugo-theme-ananke). +## Publish the site -**For further theme customization, see [Customize a Theme](/themes/customizing/).** +In this step you will _publish_ your site, but you will not _deploy_ it. -### Step 7: Build static pages +When you _publish_ your site, Hugo creates the entire static site in the `public` directory in the root of your project. This includes the HTML files, and assets such as images, CSS files, and JavaScript files. -It is simple. Just call: +When you publish your site, you typically do _not_ want to include [draft, future, or expired content]. The command is simple. -```txt -hugo -D +```text +hugo ``` -Output will be in `./public/` directory by default (`-d`/`--destination` flag to change it, or set `publishdir` in the config file). +To learn how to _deploy_ your site, see the [hosting and deployment] section. + +## Ask for help + +Hugo's [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question. + +## Other resources + +For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/external-learning-resources/) page. + +[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke +[directory structure]: /getting-started/directory-structure +[draft, future, and expired content]: /getting-started/usage/#draft-future-and-expired-content +[draft, future, or expired content]: /getting-started/usage/#draft-future-and-expired-content +[external learning resources]:/getting-started/external-learning-resources/ +[forum]: https://discourse.gohugo.io/ +[forum]: https://discourse.gohugo.io/ +[front matter]: /content-management/front-matter +[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[hosting and deployment]: /hosting-and-deployment/ +[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[Install Hugo]: /installation/ +[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows +[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132 +[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132 +[site configuration]: /getting-started/configuration/ |