diff options
Diffstat (limited to 'docs/content/en/showcase')
57 files changed, 697 insertions, 0 deletions
diff --git a/docs/content/en/showcase/1password-support/bio.md b/docs/content/en/showcase/1password-support/bio.md new file mode 100644 index 000000000..9187908d9 --- /dev/null +++ b/docs/content/en/showcase/1password-support/bio.md @@ -0,0 +1,5 @@ + +**1Password** is a password manager that keeps you safe online. It protects your secure information behind the one password only you know. + + +The [1Password Support](https://support.1password.com/) website was built from scratch with **Hugo** and enhanced with **React** and **Elasticsearch** to give us the best of both worlds: The simplicity and performance of a static site, with the richness of a hosted web app. diff --git a/docs/content/en/showcase/1password-support/featured.png b/docs/content/en/showcase/1password-support/featured.png Binary files differnew file mode 100644 index 000000000..8e46495e6 --- /dev/null +++ b/docs/content/en/showcase/1password-support/featured.png diff --git a/docs/content/en/showcase/1password-support/index.md b/docs/content/en/showcase/1password-support/index.md new file mode 100644 index 000000000..2bcbff3fd --- /dev/null +++ b/docs/content/en/showcase/1password-support/index.md @@ -0,0 +1,39 @@ +--- + +title: 1Password Support +date: 2018-02-22 +description: "Showcase: \"Compiles 400 pages in five languages in the blink of an eye.\"" +siteURL: https://support.1password.com/ +byline: "[Mitch Cohen](https://github.com/mitchchn), Documentation Team Lead" +aliases: [/showcase/1password/] + +--- + +At 1Password, we used to go through a different documentation platform every month: blog engines, ebooks, wikis, site generators written in Ruby and JavaScript. Each was inadequate in its own special way. Then we found **Hugo**. We made one last switch, and we're glad we did. + +### Not all static site generators are created equal + +Finding a tool that will make your customers, writers, designers, _and_ DevOps team happy is no easy task, but we managed it with Hugo: + +**Hugo is static**. We're a security company, so we swear by static sites and use them wherever possible. We feel much safer pointing customers at HTML files than at a complicated server which needs to be hardened. + +**Hugo is Go**. We love the Go programming language at 1Password, and we were delighted to learn that Hugo used the same Go template syntax that our designers and front-end developers had already mastered. + +**Hugo is FAST**. Our previous static site generator took nearly a minute to compile our (then much smaller) site. Developers might be used to this, but it wasn't cutting it for writers who wanted to see live previews of their work. Hugo did the same job in milliseconds, and to this day compiles 400 pages in five languages in the blink of an eye. + +**Hugo is flexible**. Thanks to Hugo's content and layout system, we were able to preserve our existing file and folder structure and port our entire production site in a few days. We could then create new content types that weren't possible before, like these snazzy [showcases](https://support.1password.com/explore/extension/). + +**Hugo is great for writers**. Our documentation team was already comfortable with Markdown and Git and could start creating content for Hugo with zero downtime. Once we added shortcodes, our writers were able to dress up articles with features like [platform boxes](https://support.1password.com/get-the-apps/) with just a bit of new syntax. + +**Hugo has an amazing developer community**. Hugo updates are frequent and filled to the brim with features and fixes. As we developed the multilingual version of our site, we submitted PRs for features we needed and were helped through the process by [@bep](https://github.com/bep) and others. + +**Hugo is simple to deploy**. Hugo has just the right amount of configuration options to fit into our build system without being too complicated. + +### Tech specs + +* [1Password Support](https://support.1password.com) uses Hugo with a custom theme. It shares styles and some template code with [1Password.com](https://1password.com), which we also moved to Hugo in 2016. +* Code and articles live in a private GitHub repository, which is deployed to a static content server using Git hooks. +* Writers build and preview the site on their computers and contribute content using pull requests. + * We use Hugo's [multilingual support](/content-management/multilingual/) to build the site in English, Spanish, French, Italian, German, and Russian. With the help of Hugo, 1Password Support became our very first site in multiple languages. +* Our [contact form](https://support.1password.com/contact) is a single-page React app. We were able to integrate it with Hugo seamlessly thanks to its support for static files. +* The one part of the support site which is not static is our search engine, which we developed with Elasticsearch and host on AWS. diff --git a/docs/content/en/showcase/alora-labs/bio.md b/docs/content/en/showcase/alora-labs/bio.md new file mode 100644 index 000000000..d304cf191 --- /dev/null +++ b/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. diff --git a/docs/content/en/showcase/alora-labs/featured.png b/docs/content/en/showcase/alora-labs/featured.png Binary files differnew file mode 100644 index 000000000..b8e1f302b --- /dev/null +++ b/docs/content/en/showcase/alora-labs/featured.png diff --git a/docs/content/en/showcase/alora-labs/index.md b/docs/content/en/showcase/alora-labs/index.md new file mode 100644 index 000000000..5e6e18131 --- /dev/null +++ b/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.
\ No newline at end of file diff --git a/docs/content/en/showcase/ampio-help/bio.md b/docs/content/en/showcase/ampio-help/bio.md new file mode 100644 index 000000000..c7dd9894a --- /dev/null +++ b/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. diff --git a/docs/content/en/showcase/ampio-help/featured.png b/docs/content/en/showcase/ampio-help/featured.png Binary files differnew file mode 100644 index 000000000..07974e7f1 --- /dev/null +++ b/docs/content/en/showcase/ampio-help/featured.png diff --git a/docs/content/en/showcase/ampio-help/index.md b/docs/content/en/showcase/ampio-help/index.md new file mode 100644 index 000000000..3d21192b8 --- /dev/null +++ b/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](/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! diff --git a/docs/content/en/showcase/bypasscensorship/bio.md b/docs/content/en/showcase/bypasscensorship/bio.md new file mode 100644 index 000000000..6563e13ca --- /dev/null +++ b/docs/content/en/showcase/bypasscensorship/bio.md @@ -0,0 +1,6 @@ +Bypass Censorship find and promote tools that provide Internet access to everyone. + +The site is built by: + +* [Leyla Avsar](https://www.leylaavsar.com/) (designer) +* [Fredrik Jonsson](https://xdeb.net/) (dev)
\ No newline at end of file diff --git a/docs/content/en/showcase/bypasscensorship/featured.png b/docs/content/en/showcase/bypasscensorship/featured.png Binary files differnew file mode 100644 index 000000000..d6f429112 --- /dev/null +++ b/docs/content/en/showcase/bypasscensorship/featured.png diff --git a/docs/content/en/showcase/bypasscensorship/index.md b/docs/content/en/showcase/bypasscensorship/index.md new file mode 100644 index 000000000..a266797ea --- /dev/null +++ b/docs/content/en/showcase/bypasscensorship/index.md @@ -0,0 +1,24 @@ +--- +title: Bypass Censorship +date: 2019-06-16 +description: "Showcase: Bypass Censorship find and promote tools that provide Internet access to everyone." +siteURL: https://www.bypasscensorship.org/ +byline: "[Fredrik Jonsson](https://xdeb.net/), Web developer & Linux sysadmin" + +--- + +The British Broadcasting Corporation (BBC) (UK), Deutsche Welle (DW) (Germany), France Médias Monde (FMM) (France), the U.S. Agency for Global Media (USAGM) (US) and the Open Technology Fund (OTF) (US) co-sponsor the Bypass Censorship website. + +Websites of international news agencies are often blocked in many countries. In order to connect people to these sites, Bypass Censorship feature and recommend tools in the following languages: English, French, Spanish, Arabic, Farsi, Chinese, and Russian. + +One of the tools is the Bypass Censorship Extension for Firefox and Chrome. The extension help direct people to mirrors of partners sites if they are being censored. + +The first version of the site was built in Drupal 8 but it was relaunched as a static site built with Hugo in 2019. + +Security, page load time and easy of hosting is the main reasons for switching to a static site. As the lead developer I had good experience with Hugo and was interested in exploring the multilingual features. + +It's a simply site, basically one page in seven languages. I had no problems getting Hugo to output what I wanted. Found the multilingual support straight forward and easy to work with. + +Thanks to the design by [Leyla Avsar](https://www.leylaavsar.com/) the site also looks good. I used the [Hugo Zen theme](https://github.com/frjo/hugo-theme-zen) with a few custom templates and the needed CSS. + +The editors can maintain content via [Forestry.io CMS](https://forestry.io/) or directly via Git. Forestry does unfortunately not have multilingual support. All the language versions are in one pile making it harder to find the right file to edit, but it works.
\ No newline at end of file diff --git a/docs/content/en/showcase/digitalgov/bio.md b/docs/content/en/showcase/digitalgov/bio.md new file mode 100644 index 000000000..db3ffafaf --- /dev/null +++ b/docs/content/en/showcase/digitalgov/bio.md @@ -0,0 +1,2 @@ + +**Digital.gov** helps people in the U.S. government deliver better, more accessible digital services through publishing essential guidance, resources, tools, and online events that make it easier for people to design, build, and deliver essential services for the public. diff --git a/docs/content/en/showcase/digitalgov/featured.png b/docs/content/en/showcase/digitalgov/featured.png new file mode 100644 index 000000000..7d065dce9 --- /dev/null +++ b/ |
