Skip to content


Browse files Browse the repository at this point in the history
Implement the Docsy theme (#561)
* Enable Docsy theme

* Set config params for use with Docsy theme

* Remove layout files which directly conflict with Docsy theme

* Add overriding blog content template

This template overrides the default Docsy file - it accounts for
multiple authors, as well as authors containing attributes. By default,
in Docsy the post's 'author' parameter is a string containing the
author's name.

* Update docs subsection layout with Docsy markup

* Add custom sidebar-nav with icons for external links

* Add hooks partials as per Docsy guidelines

Docsy provides `head-end.html` and `body-end.html` as entry-points to
extending these areas of the theme. Existing partials for applicable
scripts and stylesheets have been migrated to these new partials.

* Add theme style variables override file

* Remove Algolia DocSearch styles and script

* Enable Google search with placeholder engine

* Add optimized header logo to Docsy header

* Add shortcode for building 'Used By' logos

* Implement home page

Refactors hompage to make the switch over from Bulma to Bootstrap.
This also entails reworking some of the shortcodes, and using Docsy's
built-in features wherever possible, such as the blocks/cover shortcode.

* Disable alternate layout for root language pages in docs

* Render auth_alts pages with shortcode instead of custom layout

* Use CSS to set background on cover blocks

* Implement 'about' page

Adds content file and shortcodes as needed to implement the 'About' page
using the Docsy theme using Docsy shortcodes.

* Implement 'showcase' page

Adds content file and shortcodes as needed to implement the 'Showcase'
page using the Docsy theme using Docsy shortcodes.

* Implement 'community' page

Adds content file and shortcodes as needed to implement the 'Community'
page using the Docsy theme using Docsy shortcodes.

* Override Docsy's list community layout

Docsy has a default 'list.html' layout file, which is opinionated about
the opening copy and block structure of this page.

* Import new site stylesheet into overridden main imports

* Apply external link icon styles

* Size homepage logo responsively

* Hide root /docs leaf pages from sidebar nav

* Move FAQ to the /docs/what_is_grpc section

* Add new in-page TOC for large screens and down

This overrides the default Docsy 'baseof' for the docs section, as well
as a new partial and styles to wrap the default table of contents in an
expandable menu.

* Clean up docs index pages for basic list layout

* Implement 'alert' Docsy shortcode in content

Docsy has a single shortcode for handling the type of functionality that
several shortcodes are currently. Whether the Docsy 'alert' shortcode is
further customized later or not, this change will allow several files to
be replaced with one.

* Replace Reddit with Google Group link in footer

* Override list page layout for the docs section

This new override is in place to account for custom frontmatter params.
Currently, the index pages for individual programming languages are
given a custom layout.

* Replace alt layout with flag for language indexes

This replaces the use of an alternate layout file for programming
language home pages with a flag that can lean on the newly overidden
'docs/list.html' template file.

* Add comments to site-specific stylesheet

* Disable Docsy overrides of default Bootstrap buttons

* Add new shortcode for rendering ToC on main pages

* Override Docsy secondary color with 'gRPC blue'

* Hide subsection list on Overview page

* Override Hugo sitemap and hide legacy pages on it

The 'quickstart' and 'tutorials' pages under the root /docs folder are
to be left, but hidden from in-page navigation and indexing. This uses
the example-site Docsy sitemap.xml file to override the default Hugo
one. A frontmatter param of 'private' is used as a flag to hide the page
from the sitemap.

* Remove unused layout, partials and shortcodes

* Disable ToC on language list pages

* Translate image rendering from Bulma to Bootstrap

* Add bannner partial to main page templates

This refactors the optional banner set in the site config from Bulma to
a custom class. In order to include the partial in the base site
structure, the default 'baseof' layout file has been overriden.

* Override breadcrumb partial to display on mobile as well

* Override Docsy CSS partial with diffs from old CSS partial

* Extract language home page content to partial

* Refactor 404 page to use Docsy-like structure and classes

* Translate buttons shortcode from Bulma to Bootstrap

* Refactor contribute page to have same structure as the other standalone pages

* Fix overflow issue with docs content on small mobile screens

* Fix user logo height on 'about' page

* Apply base and responsive styling to homepage images

* Support short titles for side nav and breadcrumbs

This change makes a check for a frontmatter param for shortened titles
while building links. It also revises the name of the param from the
existing "short" to "short_title".

* Enable "simple" view of languages index page

Frontmatter param of "simple_list" is provided by Docsy

* Remove javascript partial no longer required

As Alpine is no longer in use to trigger modals and the anchor tag
offset has been generated by Docsy, the JavaScript partial can be

* Revert auto-format changes

* Give same max-width to main content as container

In the docs section and the blog, the max-width is defined by Docsy as
80%. This intentionally caps that value at the same max-width defined by
the 'container' used elsewhere for very large screens.

* Remove list bullets and increase spacing on prog-lang-home pages

* Add redirect rule for FAQ page

* Specify 'main' branch when building meta links

The gRPC repo has updated its "master" branch to the gaining-acceptance
"main" naming.

* Enable multi-language support on site

This sets up a folder structure and configuration to enable future work
to add multiple languages to the site. To add another language, create
content under an approprite content/ subdirectory and add the key to the
'languages' param in config. As soon as a second language is added, a
dropdown menu will be generated in the Docsy top nav to select the

* Revert git command in netlfy build steps

* Give supported language pages custom titles

Since this is overriding Docsy's "head" partial, the ranging over the
default "alternative output formats" and creating broken links has been
commented out of the partial as well.

* Revert "Revert git command in netlfy build steps"

This reverts commit 60a6fc0.

* Disable Docsy buttons using variable override

* Remove deprecation warning on use of '.Dir'
  • Loading branch information
aidanranney committed Dec 17, 2020
1 parent 66d4f81 commit fe23132
Show file tree
Hide file tree
Showing 208 changed files with 1,196 additions and 1,195 deletions.
1 change: 1 addition & 0 deletions assets/icons/logo.svg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
162 changes: 162 additions & 0 deletions assets/scss/_grpc.scss
@@ -0,0 +1,162 @@

.constrained-width {
margin-left: auto;
margin-right: auto;
max-width: 1140px;

.banner {
width: 100%;
position: fixed;
margin-left: -15px;
z-index: 32;
top: 4rem;
background: $gray-100;
text-align: center;

& p {
padding: 0.5rem;

.image--modal-trigger {
cursor: pointer;

a:not(.td-sidebar-link) > .fa-external-link-alt::before {
margin-left: 3px;
a > .fa-external-link-alt::before {
font-size: 50%;
opacity: 0.8;
vertical-align: top;

Docsy's 'cover/block' option for setting background images does
not currrently support svg's. This sets the background on hero
sections site wide to the original site's background svg.
.td-cover-block {
background-image: url("/img/graphic-04.svg");


// Docsy includes the site name by default. This is in place
// to hide the span text, leaving only the logo svg
.navbar-brand span:last-child {
display: none;


.homepage__logo {
width: 100%;

.homepage-features {
background-color: $gray-100;

.homepage-features__icon {
width: 50%;
margin-left: auto;
margin-right: auto;
margin-bottom: 1rem;

.homepage-cncf__logo {
margin-left: auto;
margin-right: auto;
max-width: 500px;

.about__user-logo {
max-height: 5rem;

@media screen and (min-width: 540px) {
.homepage-features {
padding-right: 3rem;
padding-left: 3rem;

@media screen and (min-width: 992px) {
.homepage-cncf__logo {
width: 50%;

.homepage-features__icon {
margin-right: 1rem;
max-width: 172px;

// In-page toc. Apply this class as a modifier to the Docsy-provided .td-toc
.td-toc--inline {
padding-top: 0;
padding-bottom: 0;
border-left: none;
position: static;
height: auto;

#td-content__toc-link span i.fa-chevron-down {
transition: transform 250ms ease-in-out;

#td-content__toc-link[aria-expanded="true"] span i.fa-chevron-down {
transform: rotate(-180deg);

// Prevent overflow on mobile devices in case of very long inline-block elements.
.td-content {
word-break: break-word;
max-width: 1140px;

/* To ensure that the top page header and description are rendered
above the inline ToC, this hides them from displaying in the main
content block */
body:not(.td-blog) .td-content:not(.list-page) {
& h1:first-child {
display: none;

& div.lead {
display: none;

// Spacing fix for page-meta-links. Whitespace in template is stripped in production.
.td-page-meta a i {
margin-right: 0.25rem;

// Language Home Pages
.prog-lang-home__list {
& h4 {
margin-bottom: 0.75rem;

& ul {
padding-left: 0.25rem;
padding-bottom: 0.5rem;
list-style: none;

& li {
padding-bottom: 0.25rem;

@media screen and (min-width: 992px) {
.td-content figure {
max-width: 80%;
12 changes: 12 additions & 0 deletions assets/scss/_variables_project.scss
@@ -0,0 +1,12 @@
// Bootstrap/Docsy variable overrides here
$primary: #244c5a;
$secondary: #5ac5c5;
$info: #379c9c;
$gray-100: #fafafa;

$display1-weight: 300;
$display2-weight: 300;

$link-color: #379c9c;

$enable-rounded: false;
66 changes: 66 additions & 0 deletions assets/scss/main.scss
@@ -0,0 +1,66 @@
// Import any new stylesheets here

@import "support/functions";
@import "variables";
@import "variables_project";
@import "support/mixins";

@import "../vendor/bootstrap/scss/bootstrap";

@import "../vendor/Font-Awesome/scss/fontawesome.scss";
@import "../vendor/Font-Awesome/scss/solid.scss";
@import "../vendor/Font-Awesome/scss/brands.scss";

@import "support/utilities";
@import "colors";
@import "boxes";
@import "blog";
@import "code";
@import "nav";
@import "sidebar-tree";
@import "sidebar-toc";
@import "buttons";
@import "breadcrumb";
@import "alerts";
@import "content";
@import "search";
@import "main-container";
@import "blocks/blocks";
@import "section-index";
@import "pageinfo";
@import "grpc";

@if $td-enable-google-fonts {
@import url($web-font-path);

footer {
min-height: 150px;

@include media-breakpoint-down(md) {
min-height: 200px;

// Adjust anchors vs the fixed menu.
@include media-breakpoint-up(md) {
.td-offset-anchor:target {
display: block;
position: relative;
top: -4rem;
visibility: hidden;

h5[id]:before {
display: block;
content: " ";
margin-top: -5rem;
height: 5rem;
visibility: hidden;

@import "styles_project";
67 changes: 66 additions & 1 deletion config.yaml
Expand Up @@ -4,8 +4,20 @@ title: gRPC
disableKinds: [taxonomy, taxonomyTerm]
pygmentsCodeFences: true

theme: ['docsy']

enableGitInfo: true

contentDir: 'content/en'
defaultContentLanguage: 'en'
defaultContentLanguageInSubdir: false

copyright: 'The Linux Foundation'
repo: &repo ''
github_repo: *repo
github_project_repo: *repo
github_branch: 'main'
branch: main
locale: en_US
Expand All @@ -14,6 +26,18 @@ params:
java: v1.34.1
font_awesome_version: 5.12.1
description: A high-performance, open source universal RPC framework
sidebar_menu_compact: true
navbar_logo: true

# If Algolia DocSearch is enabled, sidebar search is not supported
sidebar_search_disable: false

# Adds a reading time to the top of each doc.
# If you want this feature, but occasionally need to remove the Reading time from a single page,
# add "hide_readingtime: true" to the page's front matter
enable: false

show_banner: false

Expand Down Expand Up @@ -47,11 +71,44 @@ params:
hero: grpc-logo.png
footer: grpc-horizontal-white.png

- name: 'Twitter'
url: ''
icon: 'fab fa-twitter'
desc: 'Follow us on Twitter!'
- name: 'Google Groups'
url: ''
icon: 'fab fa-google'
desc: 'Join our Google community'
- name: 'GitHub'
url: ''
icon: 'fab fa-github'
desc: 'Development takes place here!'
- name: 'Gitter'
icon: 'fab fa-gitter'
desc: 'Where developers come to talk'

# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id: '788f3b1ec3a111a2f'

# Enable Algolia DocSearch
algolia_docsearch: false

#Enable offline search with Lunr.js
offlineSearch: false

renderer: {unsafe: true}
style: manni
startLevel: 2
endLevel: 5
ordered: false

# Configuration required for auto-generating the Netlify _redirects file
Expand Down Expand Up @@ -113,3 +170,11 @@ menu:
url: /faq/
weight: 7
parent: docs

title: gRPC
description: A high-performance, open source universal RPC framework
weight: 1
languageName: 'English'
languageDirection: 'ltr'
6 changes: 0 additions & 6 deletions content/docs/languages/java/

This file was deleted.

6 changes: 0 additions & 6 deletions content/docs/languages/kotlin/

This file was deleted.

6 changes: 0 additions & 6 deletions content/docs/languages/node/