Merge commit '00c4484c7092181729f6f470805bc7d72e8ad17b'

docs/content/en/showcase/alora-labs/bio.md

@@ -0,0 +1,3 @@
+**Alora Labs** is a product development consultancy headquartered in Toronto, Canada. 
+
+We help companies build software and IoT products and were recently recognized as one of the [**top IoT development firms**](https://aloralabs.com/insights/alora-labs-receives-clutch-2021-top-iot-agency-award) in Toronto.

docs/content/en/showcase/alora-labs/index.md

@@ -0,0 +1,18 @@
+---
+title: Alora Labs
+date: 2021-05-27
+description: "Showcase: \"Making performant websites accessible for everyone.\""
+siteURL: https://aloralabs.com/
+siteSource: https://github.com/aloralabs/homepage
+aliases: [/showcase/aloralabs/]
+---
+
+At Alora Labs we always have an eye open for new tools and technology that we can utilize to the benefit of our customers or internal projects like our website.
+
+The previous iteration of our site was built with Jekyll, which served us well at first. However as time went on, we became frustrated with the number of dependencies we had to rely on, that would often break at the most inconvenient times. 
+
+Hugo was a breath of fresh air in this regard, a single binary that works equally well on Windows as it did on macOS or Linux. We no longer need additional tools for image optimization, Sass compilation or JavaScript bundling. Everything just works, and with a substantial performance boost too.
+
+Hugo has become a favorite tool in the toolbelt and the foundation for many client projects. We couldn't be happier with the switch and we are optimistic about recommending Hugo for many years to come. 
+
+Thank you to the vibrant community and talented development team for all the hard work in making Hugo a success. As excellent as Hugo is now, we cannot wait to see what the release notes have in store for us next.

docs/content/en/showcase/ampio-help/bio.md

@@ -0,0 +1,11 @@
+
+__We are Ampio.__ We design and manufacture a building automation system that provides control, comfort, safety and reliability. Visit [our page](http://ampio.com/) to learn more about our solution!
+
+__Ampio Knowledge Base__ is a service built and maintained with Hugo. It is a self-service support platform for our customers and certified installers. It also contains a complete portfolio of our modules---building blocks of the Ampio building automation system.
+
+The site is built by:
+
+* [@mgetka](https://github.com/mgetka), developer
+* [@SteynAnna](https://github.com/SteynAnna), maintainer
+
+and other members of the Ampio team responsible for content creation.

docs/content/en/showcase/ampio-help/index.md

@@ -0,0 +1,77 @@
+---
+title: Ampio Knowledge Base
+date: 2022-10-30
+
+description: "Knowledge base for the Ampio building automation system."
+siteURL: https://help.ampio.com/
+---
+
+As a company that specializes in highly customizable smart solutions for various industries, Ampio has accumulated a vast amount of knowledge throughout the years. We were on the lookout for a user-friendly platform to impart this knowledge to our clients and installers. Delivering a service that caters to both audiences, scattered around the globe with vastly divergent needs and expectations, was a challenge.
+
+On the one hand, we needed something that would let us educate a client with no technical knowledge about our system in a visually appealing way.
+
+On the other hand, our installers required technical drawings, offline manuals, and a deep dive into highly specialized subjects.
+
+Over and above that, we could not overlook the fact that our internal team of editors and maintainers of the Knowledge Base included non-programmers who had to be able to create content and navigate the architecture of the site just as well as those adept at coding.
+
+We started our journey with the following requirements:
+
+ - Ease of contribution
+ - Efficient search capabilities
+ - The possibility of deployment to simple shared hosting
+ - Proper support for multilingualism
+
+## Dark ages of WordPress
+
+With the above-mentioned in mind, we built our first revision of the service in WordPress with a commercial knowledge base plugin. The initial requirements seemed not to be exorbitant, and yet we were surprised to see that only a few of the available solutions covered them. Especially, the case of multilingualism appeared to be particularly neglected across the available products.
+
+The WordPress-based products made big promises: pay some bucks, bootstrap the service in minutes, and forget about all the development troubles. And although those promises could possibly be deliverable on WordPress' end, it was definitely not true for anything more than the most generic deployments. In our case, we were dealing with more and more trade-offs. Plus, the solution was just slow on the simple shared hosting environment that we dedicated to the job.
+
+## Turning point
+
+The turning point was the introduction of a new key requirement---each document was to be downloadable in the PDF format. Such functionality was not available in the plugins we owned, nor did it look like any of the other existing WordPress plugins could fulfill our needs to a satisfactory degree. Nobody in our team was brave enough to add such a functionality to the current stack, so we decided to start from scratch.
+
+On top of that new development, we had to remember another one of our key requirements, namely, that mostly non-programmers were to be responsible for the service maintenance and content creation. Initially, we were leaning towards headless CMS-based solutions, but finally we made a bold move and decided to create a Git-managed Jamstack service and see what happens.
+
+## Hugo to the rescue!
+
+Hugo was our first choice of SSG. The multilingualism support was the primary feature that convinced us. Later on, going through the documentation, we continued to discover new exciting features that we didn't even know we needed when we started.
+
+The rich functionalities of WordPress WYSIWYG editors soon turned out to be a curse. It became burdensome to maintain formatting consistency across documents prepared by multiple contributors. When we considered Markdown, we knew that it would give us a lot less flexibility. In our case, it proved to be a blessing in disguise---the constraints imposed by the notation ensured that each document was prepared in the same way. And in the cases where Markdown was not enough, Hugo shortcodes gave us all that we needed to get the results we anticipated.
+
+In terms of PDF generation, we utilized [custom output formats](https://gohugo.io/templates/output-formats/) to produce intermediary document representations, which are consumed by our custom tool transforming them to TeX documents, which are finally used to produce PDF files.
+
+Custom output formats were also used to create search indexes. The search functionality is built on the brilliant [TNTSearch](https://github.com/teamtnt/tntsearch) library. The search queries and results are handled by PHP snippets embedded into static documents handled by Hugo.
+
+We even implemented a simple REST API generated by Hugo! We have yet to find something that cannot be achieved with this stack, while in WordPress-based solutions we were struggling with things as simple as defining custom document ordering in one of the categories list views.
+
+When talking about Hugo, we cannot forget about the speed. At the beginning we were not considering it a killer feature, but as our document base grew bigger, we appreciated it more and more. Dry-runs are not so common---most of the time we are working on one of the documents with cache already built during one of the previous Hugo runs. In such a scenario, Hugo rebuilds the site in about a second and we consider it a very good result.
+
+```
+                   | EN  | PL
+-------------------+-----+------
+  Pages            | 483 | 486
+  Paginator pages  |  56 |  55
+  Non-page files   | 745 | 749
+  Static files     | 917 | 917
+  Processed images | 487 | 490
+  Aliases          |  80 |  79
+  Sitemaps         |   2 |   1
+  Cleaned          |   0 |   0
+
+Total in 1096 ms
+```
+
+## Adaptation among the contributors
+
+Very quickly it became apparent that our initial concerns about the adaptation of the workflow among contributors were grossly exaggerated. Markdown is fairly straightforward and did not cause any trouble for the contributors.
+
+We recommended that our colleagues use Visual Studio Code as a tool for content creation. The project’s repository tracks project-scoped configuration of the editor, which includes a set of _tasks_ allowing to run a live server from the GUI level. This is very useful for those who are easily frightened when faced with the mighty terminal.
+
+The basic skills of the Git workflow were also easily acquired. At the end of the day, builds and deployments are fully managed by CI/CD processes, so the administration of the service drills down to reviewing and accepting merge requests in the Git frontend. As a side effect, we receive a full and clear history of contributions, which is well appreciated by our quality assurance auditors.
+
+We could even say that our experiment spread the love for Git among non-programmers in our organization!
+
+## Summary
+
+Hugo is the best! Definitely give it a try if you are ever faced with a challenge similar to ours. And do not give it a second thought if your service contributors are not too technically inclined---it might still turn out great!

docs/content/en/showcase/digitalgov/index.md

@@ -13,7 +13,7 @@ Through collaboration in our communities of practice, Digital.gov is a window in
 Digital.gov is built using the [U.S. Web Design System](https://designsystem.digital.gov/) (USWDS) and have followed the [design principles](https://designsystem.digital.gov/maturity-model/) in building out our new site:
 
 -   **Start with real user needs**  — We used human-centered design methods to inform our product decisions (like qualitative user research), and gathered feedback from real users. We also continually test our assumptions with small experiments.
--   **Earn trust**  —We recognize that trust has to be earned every time. We are including all  [required links and content](https://digital.gov/resources/required-web-content-and-links/)  on our site, clearly identifying as a government site, building with modern best practices, and using https.
+-   **Earn trust**  —We recognize that trust has to be earned every time. We are including all  [required links and content](https://digital.gov/resources/required-web-content-and-links/)  on our site, clearly identifying as a government site, building with modern best practices, and using HTTPS.
 -   **Embrace accessibility**  —  [Accessibility](https://digital.gov/resources/intro-accessibility/)  affects everybody, and we built it into every decision. We’re continually working to conform to Section 508 requirements, use user experience best practices, and support a wide range of devices.
 -   **Promote continuity**  — We started from shared solutions like USWDS and  [Federalist](https://federalist.18f.gov/). We designed our site to clearly identify as a government site by including USWDS’s .gov banner, common colors and patterns, and built with modern best practices.
 -   **Listen**  — We actively collect user feedback and web metrics. We use the  [Digital Analytics Program](https://digital.gov/services/dap/)  (DAP) and analyze the data to discover actionable insights. We make small, incremental changes to continuously improve our website by listening to readers and learning from what we hear.

docs/content/en/showcase/fireship/index.md

@@ -14,4 +14,4 @@ After careful consideration of JavaScript/JSX-based static site generators, it b
 - **Composability.** Hugo's partial and shortcode systems empower us to write DRY and maintainable templates.
 - **Simplicity.** Hugo is easy to learn (even without Go experience) and doesn't burden us with brittle dependencies.
 
-The site is able to achieve Lighthouse performance scores of 95+, despite the fact that it is a fully interactive PWA that ships Angular and Firebase in the JS bundle. This is made possible by (1) prerendering content with Hugo and (2) lazily embedding native web components directly in the HTML and markdown. We provide a [detailed explanation](https://youtu.be/gun8OiGtlNc) of the architecture on YouTube and can't imagine development without Hugo.
+The site is able to achieve Lighthouse performance scores of 95+, despite the fact that it is a fully interactive PWA that ships Angular and Firebase in the JS bundle. This is made possible by (1) prerendering content with Hugo and (2) lazily embedding native web components directly in the HTML and Markdown. We provide a [detailed explanation](https://youtu.be/gun8OiGtlNc) of the architecture on YouTube and can't imagine development without Hugo.

docs/content/en/showcase/forestry/bio.md

@@ -1,5 +1,4 @@
 
-Forestry.io is a Git-backed CMS (content management system) for websites and web products built using static site generators such as Hugo. 
+Forestry.io is a Git-backed CMS (content management system) for websites and web products built using static site generators such as Hugo.
 
 Forestry bridges the gap between developers and their teams, by making development fun and easy, while providing powerful content management for their teams.
-

docs/content/en/showcase/godot-tutorials/bio.md

@@ -1,9 +1,7 @@
-
 [Godot Tutorials](https://godottutorials.com) aims to teach beginners how to get up and running with basic game programming and game development skills.
 
 The website is built with the **Hugo Framework** alongside aws+cloudfront+lambda.
 
 The site is built by:
 
-* [Godot Tutorials](https://godottutorials.com)
-
+- [Godot Tutorials](https://godottutorials.com)

docs/content/en/showcase/godot-tutorials/index.md

@@ -15,11 +15,11 @@ byline: "[Godot Tutorials](https://godottutorials.com), Web Developer & Game Pro
 
 
 [Godot Tutorials](https://godottutorials.com) started as a way to teach beginners game programming and game development.
-As I created videos, I ran into a problem; if I made a mistake with a Youtube video, it was difficult to correct errors.
+As I created videos, I ran into a problem; if I made a mistake with a YouTube video, it was difficult to correct errors.
 
 I discovered that blogging episodes and having articles that teach on top of my videos is a fantastic solution to my problem.
 
-As I researched blogging platforms, I came across two solutions; however, I chose [Hugo](https://gohugo.io) because it's built with markdown in mind and simplified my workflow.
+As I researched blogging platforms, I came across two solutions; however, I chose [Hugo](https://gohugo.io) because it's built with Markdown in mind and simplified my workflow.
 
 In a sense, with [Hugo](https://gohugo.io) programmed the right way, I can focus **more time on planning, creating, and editing**
 my videos and **less time maintaining and fixing** my website.

docs/content/en/showcase/hapticmedia/index.md

@@ -1,28 +1,27 @@
 ---
-
 title: Hapticmedia Blog
 date: 2019-10-01
 description: "Showcase: \"A simple, but powerful, multilingual blog.\""
 siteURL: https://hapticmedia.fr/blog/en/
 byline: "[Cyril Bonnet](https://github.com/monsieurnebo), Web Developer"
-
 ---
 
 Our goal was to create a simple, effective and multilingual blog on [3D technology](https://hapticmedia.fr/blog/en/3d-technology/) that could be managed by a non-technical profile.
 
 ## Why Hugo?
+
 Hugo addresses all these needs, coupled with [Forestry.io](https://forestry.io/) for its administration via a "turnkey" interface. We have attached particular importance to SEO, and therefore to the creation of an advanced taxonomy system. Thus, each author and tag has a dedicated page, listing the related posts.
 
-
 ## What we liked
+
 - The **multilingual** content support, especially simple to setup.
 - The **multiple environments** support (develop, staging, test, production, ...).
 - Although a hard start with the Go language, the power of the **Hugo's templating**.
 - The **partial layouts**, including the `internals` (e.g. social meta tags).
 - The **build time**, unbeatable ⚡️⚡️⚡️.
 
-
 ## Tools & workflow
+
 - We used the same design as **[our website](https://hapticmedia.fr/en/)**, recreated as a Hugo HTML template.
 - **[Hugo](https://gohugo.io)** for the static website generator.
 - **[CircleCI](https://circleci.com)** for continuous integration & deployment.

docs/content/en/showcase/hartwell-insurance/index.md

@@ -20,7 +20,7 @@ It’s a multi-page, single-page (!) website written in Hugo, a static site gene
 
 There’s no Apache or Node backend that does compilation at runtime, it’s all done at the build step. This means the server; Netlify in this case, only has to do one thing – serve files. Unsurprisingly, serving simple files is VERY quick.
 
-The starter point was the [Victor Hugo](https://github.com/netlify/victor-hugo) repository that Netlify have created. It let me dive in with Hugo, PostCSS, BrowserSync and ES6 without setting up any tooling myself – always a win!
+The starter point was the [Victor Hugo](https://github.com/netlify/victor-hugo) repository that Netlify have created. It let me dive in with Hugo, PostCSS, Browsersync and ES6 without setting up any tooling myself – always a win!
 
 I then took all the content from the design file and moved it into Markdown, putting shortcodes in where necessary. This site did need a number of custom shortcodes for the presentational elements like the expanding circles and full width backgrounds. But mostly it was just clean, semantic HTML with some CSS and JS enhancement thrown in.
 

docs/content/en/showcase/small-multiples/bio.md

@@ -1,3 +0,0 @@
-
-Small Multiples is a multidisciplinary team of data specialists, designers and developers that help people make the best use of their data, a journey that starts from strategy, to concepts, mock-ups, prototypes, design, and development.
-

docs/content/en/showcase/small-multiples/index.md

@@ -1,47 +0,0 @@
----
-
-title: Small Multiples 
-date: 2018-02-28
-description: "\"Hugo has excellent support and integration with Netlify and we were immediately blown away by how fast it was.\""
-siteURL: https://smallmultiples.com.au/
-byline: "[Small Multiples](https://smallmultiples.com.au/)"
-draft: true
----
-
-Previously we had built and hosted our website with SquareSpace. Although SquareSpace was adequate for quickly showcasing our work, we felt it didn’t reflect our technical capabilities and the types of products we build for our clients.
-
-For many client applications, static front-end sites provide fast, scalable solutions that can easily connect with any back-end service, API or static data. We wanted to use the same processes and infrastructure that we use to host and deploy many of our products, so we felt that building a static site was the right solution for our website.
-
-Netlify is a hosting and deployment service that we use for many products. Our developers really like it because it has strong integration with GitHub and it works with the build tools we use such as Yarn and Webpack. It creates a production build every time we commit to our GitHub repository. This means we can share and preview every change internally or with clients.
-
-Application development has become increasingly complex and there is a strong motivation to simplify this process by avoiding complicated backends in favour of applications that consume static data and APIs (a JAMstack).
-
-Libraries like React make this easy, but we also wanted something that was server rendered. This led us to look at React based tools for static site generation such as GatsbyJS. We liked GatsbyJS, but in the end, we didn’t choose it due to the lack of availability of a simple CMS driven data source.
-
-For this, we considered Contentful. Contentful is a beautifully designed application. It’s basically a headless CMS, but it’s not specifically designed for websites and it becomes quite expensive at a commercial level. Their free tier is possibly a good option for personal sites especially with Gatsby. We also evaluated prose.io. This is a free service for editing markdown files in a GitHub repository. It works well, but it’s quite basic and didn’t provide the editing experience we were looking for.
-
-At the same time, we started exploring Hugo. Hugo is a static site generator similar to Jekyll, but it’s written in Go. It has excellent support and integration with Netlify and we were immediately blown away by how fast it was.
-
-We had been closely following the redevelopment of the Smashing Magazine website. We knew this was being powered by Hugo and Netlify and this showed us that Hugo could work for a large scale sites.
-
-The deciding factor, however, was the availability of CMS options that integrate well with Hugo. Netlify has an open source project called NetlifyCMS and there are also hosted services like Forestry.io. These both provide a CMS with an editing interface for markdown files and images. There is no database, instead, changes are committed directly back into the GitHub repository.
-
-In the end, we chose Hugo on Netlify, with Forestry as our CMS. The site is built and redeployed immediately with Netlify watching for changes to the GitHub repository.
-
-Was this the right choice? For us, yes, but we learnt a few things along the way.
-
-The Hugo templating language was very powerful, although also frustrating at times. The queries used to filter list pages are concise but difficult to read. Although it’s easy to get started, Hugo can have a significant learning curve as you try to do more complicated things.
-
-Hugo has particular expectations when it comes to CMS concepts like tags, categories, RSS, related content and menus. Some parts of our initial design did not match perfectly with how these work in Hugo. It took some time to figure out how to make things work the way we wanted without losing all the benefits of structured content.
-
-There were a few teething issues. We picked some relatively new technologies and as a result, we encountered some bugs. We were forced to find some workarounds and logged some issues with Hugo during the course of development. Most of these were fixed and features were added with releases happening frequently over the time we were working on the project. This can be exciting but also frustrating. We can see Hugo is developing in the right direction.
-
-NetlifyCMS was also very new when we first looked at it and this is partly why we opted for Forestry. Forestry is an excellent choice for an out-of-the-box CMS and it needs very little code configuration. It provided a better editing experience for non-technical users. I would still say this is true, but it also provides fewer options for customisation when compared with NetlifyCMS.
-
-Fortunately, the site is more portable now than it was, or would have been with a dynamic CMS like WordPress, or a fully hosted service like SquareSpace. It should be comparatively easy to swap the publishing functions from Forestry to NetlifyCMS or to change the templates. No part of the pipe-line is tightly coupled, the hosting, the CMS and the templates and the build process can all be updated independently, without changing anything else.
-
-We have complete control over the design and mark-up produced. This means we can implement a better responsive design and have a stronger focus on accessibility and performance.
-
-These technology choices gave us a good performance baseline. It was important to implement a site that took advantage of this. As a data visualisation agency, it can be difficult to optimise for performance with a small bundle size, while also aiming for high-quality visuals and working with large datasets. This meant we spent a lot of time optimising assets making sure there was little blocking the critical path for faster rendering and lazy-load images and videos.
-
-The end result is a high performance site. We think this could have been achieved with GatsbyJS, Hugo or any another static site generator. However, what was important was the decision to use static infrastructure for speed, security, flexibility and hopefully a better ongoing development experience. If you are looking at choosing a static site generator or wondering whether a static is the right choice for you, we hope this has helped.

docs/content/en/showcase/template/index.md

@@ -1,22 +1,18 @@
 ---
-
 title: Hugo Showcase Template
 date: 2018-02-07
 description: "A short description of this page."
 siteURL: https://gohugo.io/
 siteSource: https://github.com/gohugoio/hugoDocs
 byline: "[bep](https://github.com/bep), Hugo Lead"
-
 ---
-
 Have a **notable Hugo site[^1]**? We would love to feature it in this **Showcase Section**
 
-We would really appreciate if you could:
+Please:
 
-1. Fork https://github.com/gohugoio/hugoDocs
-2. Run `hugo new showcase/your-site` (this requires >= Hugo 0.49). This will use the archetype bundle in the [docs repo](https://github.com/gohugoio/hugoDocs/tree/master/archetypes).
+1. Fork https://github.com/gohugoio/hugoDocs.
+2. Run `hugo new showcase/your-site`. This will use the archetype bundle in the [docs repo](https://github.com/gohugoio/hugoDocs/tree/master/archetypes).
 3. Follow the instructions in the newly created page bundle.
-3. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls
-
+4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls.
 
 [^1]: We want this to show Hugo in its best light, so this is not for the average Hugo blog. In most cases the answer to "Is my site [notable](https://www.dictionary.com/browse/notable)?" will be obvious, but if in doubt, create an [issue](https://github.com/gohugoio/hugoDocs/issues) with a link and some words, and we can discuss it. But if you have a site with an interesting Hugo story or a company site where the company itself is notable, you are most welcome.