From 13c75f44ee321942175fc9f5f8fe72241addc9b2 Mon Sep 17 00:00:00 2001 From: Ryan Watters Date: Tue, 21 Feb 2017 14:35:54 -0600 Subject: [PATCH] Add first draft of strategy statement and content revisions --- .gitignore | 3 +- README.md | 5 +- tree.txt => annotated-content-changes.md | 52 +++++- content/news/press-and-articles.md | 1 + content/templates/partial-templates.md | 48 ++++-- doc-concept-roadmap.md | 4 +- eof-error.md | 49 ------ questions-for-reviewers.md | 1 - strategy.md | 160 ++++++++++++++++++ themes/hugodocs/layouts/_default/baseof.html | 1 + .../layouts/partials/site-header.html | 11 +- .../layouts/partials/site-search.html | 6 + 12 files changed, 256 insertions(+), 85 deletions(-) rename tree.txt => annotated-content-changes.md (82%) delete mode 100644 eof-error.md delete mode 100644 questions-for-reviewers.md create mode 100644 strategy.md create mode 100644 themes/hugodocs/layouts/partials/site-search.html diff --git a/.gitignore b/.gitignore index f7877f45c..3cb9c3f4c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ themes/hugodocs/pipeline/node_modules my-notes.md -notes-for-reviewers.md -features-log.md \ No newline at end of file +notes-for-reviewers.md \ No newline at end of file diff --git a/README.md b/README.md index 5766cd8a6..b44570d66 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,10 @@ -**Currently In Development.** This Hugo Docs concept is an attempt at implementing the new docs source organization found here: +**CURRENTLY IN DEVELOPMENT.** This Hugo Docs concept is a complete reworking of the HUGO documentation. I originally broached the subject of a documentation overhaul here: ## Contributing to the Docs -## Suggestions for Improvements - +(WIP) See the guide at for instructions on how to contribute to the documentation. \ No newline at end of file diff --git a/tree.txt b/annotated-content-changes.md similarity index 82% rename from tree.txt rename to annotated-content-changes.md index 09779eb21..fdb09218c 100644 --- a/tree.txt +++ b/annotated-content-changes.md @@ -1,3 +1,50 @@ + + +- [Changes to Existing Content Sections][changes-to-existing-content-sections] + - [Extras][extras] + - [Tutorials][tutorials] +- [Content Organization \(Site\)][content-organization-site] +- [Content Organization \(Source\)][content-organization-source] + + + + + + +## Changes to Existing Content Sections + +The following is an *abbreviated* listing and only includes the *larger* changes to content organization + + +### [Extras](http://gohugo.io/extras) + +* This section no longer exists in the new documentation site + * *Extras*, in the content world, is the equivalent of *miscellaneous* or *additional resources*. READ: "We don't have any idea of where to put this" +* Previous pages in extras are now in the following locations: + * **Aliases** Incorporated into `/content-management/url-management/` + * **Analytics** Incorporated into /templates/partial-templates/#built-in + + +### [Tutorials](http://gohugo.io/tutorials) + +* Moved all installation guides to /getting-started/install-hugo/ + * Installing Hugo shouldn't be considered a separate tutorial + * "Tutorials" is not an intuitive place for end-users to look for this kind of documentation +* All content moved from `/tutorials` edited to reflect a less tutorial-ish style of language (e.g., remove of lines starting with "In this tutorial...") +* Aliases added to new pages and in-page links updated throughout + + + +## Content Organization (Site) + +The following is a list of weights for the newly restructure site architecture + + +## Content Organization (Source) + +**2017-02-21 New Content Reorganization** + +``` . ├── _index.md ├── about-hugo @@ -262,14 +309,14 @@ │   ├── customizing-a-theme.md │   ├── installing-and-using-themes.md │   └── theme-showcase.md -├── tree.txt ├── troubleshooting │   ├── _index.md │   ├── accented-characters-in-urls.md │   └── eof-error.md ├── tutorials │   ├── _index.md -│   ├── creating-a-multilingual-site.md +│   ├── create-a-multilingual-site.md +│   ├── creating-a-new-theme.md │   └── migrate-from-jekyll-to-hugo.md └── variables-and-params ├── _index.md @@ -280,3 +327,4 @@ └── taxonomy-variables.md 15 directories, 264 files +``` \ No newline at end of file diff --git a/content/news/press-and-articles.md b/content/news/press-and-articles.md index 054a587f0..edf1fb4df 100644 --- a/content/news/press-and-articles.md +++ b/content/news/press-and-articles.md @@ -23,6 +23,7 @@ Hugo has been featured in the following Blog Posts, Press, and Media. | Title | Author | Date | | ----- | ------ | -----: | | [How to Password Protect a Hugo Site](https://www.aerobatic.com/blog/password-protect-a-hugo-site/) | Aerobatic | 2017-02-19 | +| [Switching from Wordpress to Hugo](http://schnuddelhuddel.de/switching-from-wordpress-to-hugo/) | http://schnuddelhuddel.de/ | 2017-02-19 | ] | [Deploy a Hugo site to Aerobatic with CircleCI ](https://www.aerobatic.com/blog/hugo-github-circleci/) | Aerobatic | 2017-02-14 | | [NPM scripts for building and deploying Hugo site]() | Aerobatic | 2017-02-12 | | [Build a Hugo site using Cloud9 IDE and host on App Engine](https://loyall.ch/lab/2017/01/build-a-static-website-with-cloud9-hugo-and-app-engine/)| Pascal Aubort | 2017-02-05 | diff --git a/content/templates/partial-templates.md b/content/templates/partial-templates.md index 1e5ceb615..0b01f460c 100644 --- a/content/templates/partial-templates.md +++ b/content/templates/partial-templates.md @@ -149,7 +149,7 @@ you can pass as many variant parameters as you need: Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key. -## Built-in Partials +## Using the Built-in Partials * Google Analytics Hugo ships with prebuilt internal templates for Google Analytics tracking, including both synchronous and asynchronous tracking codes. @@ -180,31 +180,39 @@ Hugo ships with support for [Disqus](https://disqus.com/), a third-party service Your theme may already support Disqus, but even it if doesn’t, it is easy to add. -# Disqus Support +### Disqus Support -## Adding Disqus to a template +#### Adding Disqus to a template Hugo comes with all the code you would need to include load Disqus. Simply include the following line where you want your comments to appear: {{ template "_internal/disqus.html" . }} -## Configuring Disqus +#### Configuring Disqus -That template requires you to set a single value in your site config file, e.g. config.yaml. +That template requires you to set a single value in your site `config`: - disqusShortname = "XYW" +```toml +disqusShortname = "yourdiscussshortname" +``` -Additionally, you can optionally set the following in the front matter -for a given piece of content: +Or with a `config.yml`: - * **disqus_identifier** - * **disqus_title** - * **disqus_url** +```yaml +disqusShortname: "yourdiscussshortname" +``` -## Conditional Loading of Disqus Comments +You also have the option to set the following in the front matter for a given piece of content: -Users have noticed that enabling Disqus comments when running the Hugo web server on localhost causes the creation of unwanted discussions on the associated Disqus account. In order to prevent this, a slightly tweaked partial template is required. So, rather than using the built-in `"_internal/disqus.html"` template referenced above, create a template in your `partials` folder that looks like this: +* `disqus_identifier` +* `disqus_title` +* `disqus_url` +#### Conditional Loading of Disqus Comments + +Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account. In order to prevent this, a slightly tweaked partial template is required. So, rather than using the built-in `"_internal/disqus.html"` template referenced above, create a template in `layouts/partials` that looks like the following: + +{{% input "layouts/partials/disqus.html" %}} ```html