diff options
Diffstat (limited to 'content/en/getting-started')
| -rw-r--r-- | content/en/getting-started/_index.md | 3 | ||||
| -rw-r--r-- | content/en/getting-started/configuration-markup.md | 73 | ||||
| -rw-r--r-- | content/en/getting-started/configuration.md | 52 | ||||
| -rw-r--r-- | content/en/getting-started/external-learning-resources/hia.jpg | bin | 0 -> 228017 bytes | |||
| -rw-r--r-- | content/en/getting-started/external-learning-resources/index.md | 29 | ||||
| -rw-r--r-- | content/en/getting-started/installing.md | 8 | ||||
| -rw-r--r-- | content/en/getting-started/quick-start.md | 4 |
7 files changed, 116 insertions, 53 deletions
diff --git a/content/en/getting-started/_index.md b/content/en/getting-started/_index.md index 478d1eaa6..1615bdd91 100644 --- a/content/en/getting-started/_index.md +++ b/content/en/getting-started/_index.md @@ -17,7 +17,8 @@ aliases: [/overview/introduction/] toc: false --- -If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][]. +If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][]. You can also use [external learning resources][] to learn Hugo. [installed]: /getting-started/installing/ [quick start]: /getting-started/quick-start/ +[external learning resources]: /getting-started/external-learning-resources/ diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md new file mode 100644 index 000000000..2a24fcdd0 --- /dev/null +++ b/content/en/getting-started/configuration-markup.md @@ -0,0 +1,73 @@ +--- +title: Configure Markup +description: How to handle Markdown and other markup related configuration. +date: 2019-11-15 +categories: [getting started,fundamentals] +keywords: [configuration,highlighting] +weight: 65 +sections_weight: 65 +slug: configuration-markup +toc: true +--- + +## Configure Markup + +{{< new-in "0.60.0" >}} + +See [Goldmark](#goldmark) for settings related to the default Markdown handler in Hugo. + +Below are all markup related configuration in Hugo with their default settings: + +{{< code-toggle config="markup" />}} + +**See each section below for details.** + +### Goldmark + +[Goldmark](https://github.com/yuin/goldmark/) is from Hugo 0.60 the default library used for Markdown. It's fast, it's [CommonMark](https://spec.commonmark.org/0.29/) compliant and it's very flexible. Note that the feature set of Goldmark vs Blackfriday isn't the same; you gain a lot but also lose some, but we will work to bridge any gap in the upcoming Hugo versions. + +This is the default configuration: + +{{< code-toggle config="markup.goldmark" />}} + +Some settings explained: + +unsafe +: By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on. + +typographer +: This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/). + +### Blackfriday + + +[Blackfriday](https://github.com/russross/blackfriday) was Hugo's default Markdown rendering engine, now replaced with Goldmark. But you can still use it: Just set `defaultMarkdownHandler` to `blackfriday` in your top level `markup` config. + +This is the default config: + +{{< code-toggle config="markup.blackFriday" />}} + +### Highlight + +This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/). + +{{< code-toggle config="markup.highlight" />}} + +For `style`, see these galleries: + +* [Short snippets](https://xyproto.github.io/splash/docs/all.html) +* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html) + +For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css). + +### Table Of Contents + +{{< code-toggle config="markup.tableOfContents" />}} + +These settings only works for the Goldmark renderer: + +startLevel +: The heading level, values starting at 1 (`h1`), to start render the table of contents. + +endLevel +: The heading level, inclusive, to stop render the table of contents.
\ No newline at end of file diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 4fea87723..a53612ff4 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -184,11 +184,14 @@ log (false) logFile ("") : Log File path (if set, logging enabled automatically). +markup +: See [Configure Markup](/getting-started/configuration-markup).{{< new-in "0.60.0" >}} + menu : See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu). module -: Module config see [Module Config](/hugo-modules/configuration/). +: Module config see [Module Config](/hugo-modules/configuration/).{{< new-in "0.56.0" >}} newContentEditor ("") : The editor to use when creating new content. @@ -214,26 +217,8 @@ pluralizeListTitles (true) publishDir ("public") : The directory to where Hugo will write the final static site (the HTML files etc.). -pygmentsOptions ("") -: A comma separated list of options for syntax highlighting. See the [Syntax Highlighting Options](/content-management/syntax-highlighting/#options) for the full list of available options. - -pygmentsCodeFences (false) -: Enables syntax highlighting in [code fences with a language tag](/content-management/syntax-highlighting/#highlight-in-code-fences) in markdown. - -pygmentsCodeFencesGuessSyntax (false) -: Enable syntax guessing for code fences without specified language. - -pygmentsStyle ("monokai") -: Color-theme or style for syntax highlighting. See [Pygments Color Themes](https://help.farbox.com/pygments.html). - -pygmentsUseClasses (false) -: Enable using external CSS for syntax highlighting. - -pygmentsUseClassic (false) -: Enable using Pygments instead of the much faster Chroma for syntax highlighting. - related -: See [Related Content](/content-management/related/#configure-related-content). +: See [Related Content](/content-management/related/#configure-related-content).{{< new-in "0.27" >}} relativeURLs (false) : Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. @@ -365,9 +350,9 @@ To set config params, prefix the name with `HUGO_PARAMS_` Test and document setting params via JSON env var. {{< /todo >}} -## Ignore Files When Rendering +## Ignore Content Files When Rendering -The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering: +The following statement inside `./config.toml` will cause Hugo to ignore content files ending with `.foo` and `.boo` when rendering: ``` ignoreFiles = [ "\\.foo$", "\\.boo$" ] @@ -436,29 +421,6 @@ The above will try first to extract the value for `.Date` from the filename, the `:git` : This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site config. -## Configure Blackfriday - -[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine. - -Hugo typically configures Blackfriday with sane default values that should fit most use cases reasonably well. - -However, if you have specific needs with respect to Markdown, Hugo exposes some of its Blackfriday behavior options for you to alter. The following table lists these Hugo options, paired with the corresponding flags from Blackfriday's source code ( [html.go](https://github.com/russross/blackfriday/blob/master/html.go) and [markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)). - -{{< readfile file="/content/en/readfiles/bfconfig.md" markdown="true" >}} - -{{% note %}} -1. Blackfriday flags are *case sensitive* as of Hugo v0.15. -2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting. -{{% /note %}} - -{{< code-toggle file="config" >}} -[blackfriday] - angledQuotes = true - fractions = false - plainIDAnchors = true - extensions = ["hardLineBreak"] -{{< /code-toggle >}} - ## Configure Additional Output Formats Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats][] for information on how to add these values to your Hugo project's configuration file. diff --git a/content/en/getting-started/external-learning-resources/hia.jpg b/content/en/getting-started/external-learning-resources/hia.jpg Binary files differnew file mode 100644 index 000000000..ee45b0e9e --- /dev/null +++ b/content/en/getting-started/external-learning-resources/hia.jpg diff --git a/content/en/getting-started/external-learning-resources/index.md b/content/en/getting-started/external-learning-resources/index.md new file mode 100644 index 000000000..4e342a6e6 --- /dev/null +++ b/content/en/getting-started/external-learning-resources/index.md @@ -0,0 +1,29 @@ +--- +title: External Learning Resources +linktitle: External Learning Resources +description: A list of tutorials and books on Hugo. +date: 2019-10-20 +publishdate: 2019-10-20 +lastmod: 2019-10-20 +keywords: [books,tutorials,learning,usage] +menu: + docs: + parent: "getting-started" + weight: 70 +weight: 70 +sections_weight: 70 +draft: false +toc: false +--- + +## Books +### Hugo In Action +[](https://www.manning.com/books/hugo-in-action) + +Hugo in Action is a step-by-step guide to using Hugo to create static websites. Working with a complete example website and source code samples, you’ll learn how to build and host a low-maintenance, high-performance site that will wow your users and stay stable without relying on a third-party server. + +[Hugo In Action Home Page](https://www.manning.com/books/hugo-in-action) + +## Video tutorials +### Video Playlist by Mike Dane +Mike Dane expains the various features of via dedicated tutorials on [Youtube](https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3&v=qtIqKaDlqXo). diff --git a/content/en/getting-started/installing.md b/content/en/getting-started/installing.md index bffbb777e..55c876646 100644 --- a/content/en/getting-started/installing.md +++ b/content/en/getting-started/installing.md @@ -463,6 +463,8 @@ Hugo installed via Snap can write only inside the user’s `$HOME` directory---a This installs the "extended" Sass/SCSS version. +This option is not recommended because the Hugo in Linux package managers for Debian and Ubuntu is usually a few versions behind as described [here](https://github.com/gcushen/hugo-academic/issues/703) + ### Arch Linux You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also to derivatives such as Manjaro. @@ -502,12 +504,6 @@ OpenBSD provides a package for Hugo via `pkg_add`: Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH` or run `brew upgrade hugo` if using Homebrew. -## Install Pygments (Optional) - -The Hugo executable has one *optional* external dependency for source code highlighting ([Pygments][pygments]). - -If you want to have source code highlighting using the [highlight shortcode][], you need to install the Python-based Pygments program. The procedure is outlined on the [Pygments homepage][pygments]. - ## Next Steps Now that you've installed Hugo, read the [Quick Start guide][quickstart] and explore the rest of the documentation. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][forum]. diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md index 143dc0a41..3c8eb6b8a 100644 --- a/content/en/getting-started/quick-start.md +++ b/content/en/getting-started/quick-start.md @@ -21,7 +21,9 @@ toc: true {{% note %}} This quick start uses `macOS` in the examples. For instructions about how to install Hugo on other operating systems, see [install](/getting-started/installing). -It is recommended to have [Git](https://git-scm.com/downloads) installed to run this tutorial. +It is recommended to have [Git installed](https://git-scm.com/downloads) to run this tutorial. + +For other approaches learning Hugo like book or a video tutorial refer to the [external learning resources](/getting-started/external-learning-resources/) page. {{% /note %}} |
