matrix-org / docsy

A set of Hugo doc templates for launching open source content.

Docsy

Note: This is standard docsy but with remote js/font files replaced with local copies.

🚧 WARNING 🚧 : main is under development and potentially unstable! Use official Docsy releases.

Docsy is a Hugo theme for technical documentation sets, providing simple navigation, site structure, and more.

This is not an officially supported Google product. This project is actively being maintained.

Prerequisites

The following are basic prerequisites for using Docsy in your site:

• Install a recent release of the Hugo "extended" version. If you install from the Hugo release page, make sure you download the extended version, which supports SCSS.

• Install PostCSS so that the site build can create the final CSS assets. You can install it locally by running the following commands from the root directory of your project:

  npm install --save-dev autoprefixer
  npm install --save-dev postcss-cli

  Starting in version 8 of postcss-cli, you must also separately install postcss:

  npm install -D postcss

Any additional prerequisites depend on the installation option you choose. We recommend using Docsy as a Hugo module, which requires that you have the go language installed in addition to Hugo and PostCSS.

For complete prerequisites and instructions, see our Get started guides.

Example and usage

You can find an example project that uses Docsy in the Docsy Example Project repo.The Docsy Example Project is hosted at example.docsy.dev. For real-life examples of sites that use Docsy (and their source repos), see our Examples page.

To use the Docsy theme for your own site:

• (Recommended) Use the example project, which includes the Docsy theme as a Hugo module, as a template to create your project. You can customize this pre-configured basic site into your own Docsy themed site. Learn more...

• Add Docsy to your existing Hugo site. You can add Docsy as a Hugo module, as a Git submodule, or clone the Docsy theme into your project.

See the Get started guides for details about the various usage options.

Documentation

Docsy has its own user guide (using Docsy, of course!) with lots more information about using the theme. It is hosted by Netlify at docsy.dev. For deploy logs and more, see Deploys from the site's Netlify dashboard.

Alternatively you can use Hugo to generate and serve a local copy of the guide (also useful for testing local theme changes), making sure you have installed all the prerequisites listed above:

git clone --depth 1 https://github.com/google/docsy.git
cd docsy/userguide/
npm install
npm run serve

Contributing

Read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us. Thank you to all past, present, and future contributors!

License

This project is licensed under the Apache License 2.0 - see the LICENSE.md file for details

docsy's Issues

docsy theme still causes outgoing connections to Google Fonts for Arabic and Hebrew languages

We use the docsy theme as part of spec.matrix.org / (source code). The changes we've currently made downstream to docsy are listed at google/docsy@main...matrix-org:docsy:master.

In terms of preventing fonts being loaded from google fonts, we've so far replaced the default font (Open Sans) with Inter, and replaced the default behaviour of loading the font from Google Fonts with a locally downloaded copy. That local copy was generated using a custom script, download_google_fonts_css.py.

Note that the replacement code above requires setting $td-enable-google-fonts to true (the default) in order for docsy to load our font.

In addition to this default font, docsy also downloads some extra fonts for Persian, Arabic and Hebrew:

docsy/assets/scss/rtl/_main.scss

Lines 33 to 51 in 66a4e61

	body:lang(fa) {
	@import url('https://cdn.jsdelivr.net/gh/rastikerdar/[email protected]/dist/font-face.css');
	font-family: 'Vazir', "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
	}
	body:lang(he) {
	@if $td-enable-google-fonts {
	@import url('https://fonts.googleapis.com/css2?family=Rubik:wght@300;400;500;600;700&display=swap');
	}
	font-family: 'Rubik', "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
	}
	body:lang(ar) {
	@if $td-enable-google-fonts {
	@import url('https://fonts.googleapis.com/css2?family=Tajawal:wght@300;400;500;700&display=swap');
	}
	font-family: 'Tajawal', "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
	}

Hebrew and Arabic are loaded from Google Fonts, whereas Persian is loaded via cdn.jsdelivr.net.

Ideally we'd host these locally as well, though the font-family: 'Rubik', "Open Sans", ... line above indicates that Open Sans acts as a fallback in these cases, so it appears fine to disable them completely - the font just might not look as nice.

I'd like to disable loading fonts from Google Fonts (and ideally all third-party sources) entirely, while also keeping the number of downstreams changes to docsy to a minimum. Therefore I propose we:

• Remove the current hack to set the default font to Inter.
• Import Inter directly ourselves: @import url("../css/fonts/Inter.css").
• Set $font-family-sans-serif to what docsy defines, but with "Inter" prepended. (Unfortunately we can't import this from docsy and prepend, as our variables will be loaded first.)
• Set $td-enable-google-fonts to false.

The above should prevent any attempts to load fonts from Google Fonts, but we're still left with loading Vazir from cdn.jsdelivr.net. That can be fixed with some more surgery on our fork of docsy, but let's leave that to a separate issue.

cc @jaller94