Git Product home page Git Product logo

docsy's Introduction

Docsy

Project status: active – The project has reached a stable, usable state and is being actively developed. Project releases Project build Status Project contributors Project license

🚧 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

For details on our code of conduct and the process for submitting pull requests, see CONTRIBUTING.md. 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 People

Contributors

aborruso avatar aimeeu avatar alexearnshaw avatar arhell avatar arnaudlevy avatar at055612 avatar atharwa-24 avatar bep avatar chalin avatar chenopis avatar coliff avatar deining avatar dependabot[bot] avatar emckean avatar fekete-robert avatar geriom avatar gwatts avatar ianlewis avatar lisafc avatar marzal avatar narrenfrei avatar richieescarez avatar rionam avatar samiahmedsiddiqui avatar sarahmaddox avatar sharifsalah avatar stephanlachnit avatar tekezo avatar theletterf avatar xu-xihe avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

docsy's Issues

Add deployment checklist

There’s a lot of moving parts in Docsy / Hugo. If this is the first time someone is setting up a standalone site, there’s a lot to think about, such as linking to a privacy policy, search config, accessibility, and handling contributions.

Consider adding a deployment checklist to allow the site manager to run through and make sure they’ve configured and tested everything they should be thinking about before they share the new site with the world.

Title off center on mobile

The title is off center because of assets/icons/logo.svg being being included in the html. If the file is deleted then an error is generated during rendering. I couldn't figure out a way to conditionally include the logo from the assets/ directory. Page resources can't read it and readFile doesn't seem to work either.

Screenshot 2019-03-14 at 19 35 07

Feature: shortcode to show/hide sections of content

Thinking about scenarios in which you have continuous (or near continuous) website deployments - you will likely want to write documentation that doesn't get published until after the next release date.

This fine at the page level - we have the front matter of expiryDate and publishDate.

But if we want to do it in sections within a page, this isn't possible at this time (unless I'm missing something).

I would suggest docsy ships with a shortcode for managing this type of scenario, something like:

{{% feature expiryDate="2018-12-31" %}}
This is the old documentation for the old version of this feature
{{% /feature  %}}

{{% feature publishDate="2018-12-31" %}}
This is the new documentation for the new version of this feature. Look how fancy it is!
{{% /feature  %}}

(Not sure if "feature" is the right name - but consider it a sacrificial draft)

What do you think?

I can do this myself, but thought it would be nicer if it was built in.

(The other idea I had, was rather than tie it to dates, tie it to a project semver, but that's probably too opinionated)

Docsy logo isn't scaling properly

As demonstrated here: https://serene-roentgen-10fbaa.netlify.com/

(I hadn't updated the theme on that site in a while so I only noticed it today when I was fixing some bits)

For some reason the relevant element is the right height but 500 px wide, and it's throwing the entire top navbar off. Dunno do we need to fix it in CSS or in the actual SVG file. Will experiment.

Prevent <code> from wrapping

In a laptop-sized browser window, I encountered some unpleasantly wrapped text on the Kubeflow website (see the left column of this screenshot).

Docsy already sets white-space: pre for pre > code. Could we apply the same style for inline code as well?

I think it's very unlikely that you would ever want a <code>...</code> element to wrap: in general they are short, and I think it's more pleasant to view the type of identifiers or code snippets in these blocks uninterrupted/pushed to the next line, rather than wrapped.

The one issue you could run into is that the code element overflows off the right edge of its parent on a very small screen, but I think this is almost impossible (would require a very long string to overrun even a small mobile screen). (You could also add a media query to tell <code> to only wrap on small screens, but this seems like overkill.)

Add new index-landing layout

Create a layout for generating "index-type" landing pages in docs sections, eg with a list of all the topics in a particular section.

Make the search box in the left-hand nav optional

Currently, if you enable the search in Docsy, you get two search boxes: One at the right of the top menu bar, the other at the top of the left-hand nav.

For my site (Kubeflow) I want just the top right search box, not the one in the left nav. To do that, I need to create a custom sidebar-tree.html to override the theme's sidebar-tree. (PR ttps://github.com/kubeflow/website/pull/471.)

Instead, it'd be nice if the double location of the search box was optional. (I guess there may be some sites that'd like the search only in the left nav and not at top right.)

Add a custom (s)css styles file

Currently there is a _custom_variables.scss that you can write as part of your project but it's loaded before other scss files and can only override certain variables. Adding some custom scss styles there works but many can't be overridden.

The alternative is to override an scss file but you need to override it in it's entirety which isn't ideal.

proposal: Add a _custom_styles.scss file that gets imported in main.scss after other styles so it can override them.

Adjust header and footer to open external links in new tab

By default, Docsy opens all external links in a new tab, when those links are part of a page. This is due to the following config.toml setting:

[blackfriday]
hrefTargetBlank = true

For consistency, if there are external links in the header and footer (such as the privacy policy), Docsy should by default open those links in a new tab.

The following PR shows how I achieved this in Kubeflow:
https://github.com/kubeflow/website/pull/500/files

Community page layout is a bit odd

The padding around the text, etc. on the community page is a bit unsatisfactory (possibly because I wrote it in a hurry before a demo) - @markmandel, you don't fancy tidying it up, do you?

Update Hugo branding in RSS XML feed

The term 'Hugo' appears in the generated RSS when it shouldn't:

<rss xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
<channel>
<title>OpenCue – New Releases</title>
<link>/blog/releases/</link>
<description>Recent Hugo news from gohugo.io</description>
<generator>Hugo -- gohugo.io</generator>
<lastBuildDate>Fri, 15 Feb 2019 19:06:19 -0500</lastBuildDate>
<image>
<url>img/hugo.png</url>
<title>GoHugo.io</title>
<link>/blog/releases/</link>
</image>

I believe this is caused by the contents of the RSS XML template.

Specifically this section:

<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>{{ .Site.Title }} – {{ .Title }}</title>
    <link>{{ .Permalink }}</link>
    <description>Recent Hugo news from gohugo.io</description>
    <generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
    <language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
    <managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
    <webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
    <copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
    <lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
    <image>
      <url>{{ "img/hugo.png" | absURL }}</url>
      <title>GoHugo.io</title>
      <link>{{ .Permalink }}</link>
    </image>

Ideally, the template needs to be updated to populate the , <title>, <image from variables so that the tenant Docsy sites don't need to overrider this template locally.

Broken future release notes date

Setting the date for a release notes post in Docsy generates an error when running the hugo command. I think this is likely to be a common use-case for projects that are planning release notes or blog posts for a future date prior to launch.

I think this issue qualifies as a bug, so I wanted to log it to save others troubleshooting until a fix is identified and implemented.

Steps to reproduce

Follow the steps to clone and run the docsy-example:

git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
cd docsy-example
hugo server

Open the following file for editing:

content/en/blog/releases/in-depth-monoliths-detailed-spec.md

Change the date in the included release notes to be any date in the future:

date: 2020-03-20

If required, install any dependencies via npm.

Run the hugo command, which produces the following error for me:

Error: Error building site: failed to render pages: render of "section" failed: "<redacted>/docsy-example/themes/docsy/layouts/blog/list.html:7:11": execute of template failed: template: blog/list.html:7:11: executing "main" at <.Paginate>: error calling Paginate: cannot convert type hugolib.PagesGroup to Pages

This error disappears if there are also other release notes with dates in the past. The problem only seem to occur if I set the date to the future for the first release note. I haven't tested this issue for regular blog posts.

Missing SCSS file

When I tried to update to the latest version of Docsy, I got the following error when I tried to run hugo server:

ERROR <date> error: failed to transform resource: SCSS processing failed: file "stdin", line 27, col 1: File to import not found or unreadable: section-index.

It looks to me like section-index.scss is in the wrong directory for the import statement in main.scss to work:

@import "section-index"; 

section-index is currently under the assets directory, while it looks like it should be under assets/scss

Fine grain UI configuration options

While the Docsy template does allow users to override UI elements, we should consider "chunking" out certain parts and their corresponding configuration so that overriding "look and feel" of any site has less overhead.

For example, the Community page allows you to set text and URLs through configuration parameters (config.toml), is it possible to use that model to allow easier manipulation of more than just text (like the size, position, behavior of UI elements)?

The footer should allow a more flexible copyright statement

The Docsy footer should allow copyright statements of the following form:

Copyright 2018 The <product_name> Authors | Documentation Distributed under CC BY 4.0

Also, we should allow the site to specify a fixed copyright date - the date should not adjust to the current calendar year.

Increase color contrast of some texts and links

Some text and links in the default Docsy styles result in low contrast. According to WCAG, text should have a contrast ratio of at least 4.5:1.

The most noticeable example of poor contrast I've noticed so far is on the /community page in the example site. The contrast of the links in the middle section against the background is 3.17:1.

'Out of the box', it would be great if the Docsy example and theme demonstrated a design that maintained a contrast ratio of 4.5:1 throughout. There are various tools that can automate checking contrast across a site or page.

Accessibility: Footer icons have no readable content for screen readers

Currently, the footer contains six icons representing links:
iconsblock1
iconsblock2

These icons have no associated label or content that can be read by a screen reader. Using ChromeVox with default settings, they'll be read as "link list item" (identifying the icon as a link first, then as an item in a list). The exact description may change depending on the screen reader and its settings.

I'm not sure how viable this is, but if possible, the aria-label attribute should probably be added to the a element for each in order to provide context for screen readers.

Error executing "shortcodes/blocks/cover.html" at <.Fit>

Hallo to the Docsy team

I've just merged the latest version of Docsy into the Kubeflow website. When building the site after the merge, I got the following error:

$ hugo server -D
Total in 387 ms
Error: Error building site: "/home/sarahmaddox/github-repos/kubeflow/website-2/content/_index.html:19:1": failed to render shortcode "blocks/cover": "/home/sarahmaddox/github-repos/kubeflow/website-2/themes/docsy/layouts/shortcodes/blocks/cover.html:31:139": execute of template failed: template: shortcodes/blocks/cover.html:31:139: executing "shortcodes/blocks/cover.html" at <.Fit>: can't evaluate field Fit in type resource.Resource

I removed the following update from the file themes/docsy/layouts/shortcodes/blocks/cover.html:31:139:

         {{ with .Get "title" }}<h1 class="display-1 mt-0 mt-md-5 pb-4">{{ $title := . }}{{ with $logo_image }}{{ $logo_image_resized := (.Fit (printf "70x70 %s" $logo_anchor)) }}<img class="td-cover-logo" src="{{ $logo_image_resized.RelPermalink }}" alt="{{ $title | html }} Logo">{{ end }}{{ $title | html }}</h1>{{ end }}

And replaced it with the previous version of the line:

         {{ with .Get "title" }}<h1 class="display-1 mt-0 mt-md-5 pb-4">{{ . | html }}</h1>{{ end }}

The site now builds correctly.

The Docsy change was introduced in this PR:
https://github.com/google/docsy/pull/16/files#diff-ca2eecf7bb5b8a4697b935a9fd894fd5R30

This is the Kubeflow index file that the error refers to, and which uses the cover block:
https://github.com/kubeflow/website/blob/master/content/_index.html#L19

Here's my PR which merges the Docsy updates (except the line mentioned above) into the Kubeflow website:
kubeflow/website#441

@ianlewis or anyone else who can help: Do you have any idea why we're getting the above error when merging this change into the Kubeflow site?

How do we find out whether people clicked "Yes" or "No" on the feedback widget?

This PR added the feedback widget:
#1

Please would you add some usage docs for interpreting the results of the widget?
(I've found the feedback event in Google Analytics for my site, but I can't figure out whether people clicked "Yes" or "No" on the feedback widget. At first I thought everyone is just clicking yes, because the only event I see is "helpful" - there's no "not helpful" event. But now 2 months have passed and there's still no "not helpful" event so I'm beginning to think there must be some other way of reading the input.)

Search functionality using local search instead of GCS

Goal

To have a local search functionality (indexing words locally) instead of GCS into the internet.

More

First, I found docsy is a great theme for my internal/personal documentation/handbook. In production, I separate the contents (writings) with a static page generator. What functionality I love is indexing and searching capability through a lot of articles I have.

Feature request

  • Is there any roadmap to add local search functionality to docsy theme?
  • Is this only for Google team's needs btw?

Thank you.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.