HandyDocs is a documentation boilerplate template for projects that don't have or require complex documentation. It is designed to give users a clear, concise overview of the documentation provided.

Built with modern technologies:

• Next.js & React
  • SSG
  • dynamic imports
  • chakra-ui
• Typescript
• MDX
  • batteries-included styling
  • custom components
• SCSS

With this tech stack, each HandyDocs instance is easily configurable & customizable to suite your project.

Easy as 1, 2, 3!

1. Fork the chroline/handydocs template repo. This will give you a blank canvas for your HandyDocs instance.

   Or, use degit to scaffold your project by running degit chroline/handydocs.

2. Clone your forked repo to your local machine.

   git clone *YOUR_REPO*
   

3. Customize your instance and add content.

...and then you're done!

Since HandyDocs is built with JAMStack technologies, you can deploy your instance to your favorite serverless/static web host provider like Vercel or Netlify.

There are 3 main parts to the HandyDocs configuration file:

1. SEO — search engine optimization; metadata about your site (site title, favicon, open graph images, etc.)
2. Hero content — styling and content for the hero
3. Table of contents — title of each content section

Each part will be explained more in-depth in their respective documentation sections.

The HandyDocs configuration file uses the YAML markup language and adheres to a strict structure, represented by the following Typescript interface:

interface ConfigFile {
  seo: any;

  hero: {
    style: {
      light: { bg: string; color: string; }
      dark?: { bg: string; color: string; }
    }
    logo: { text: string; }
    subheading: string;
    info_boxes: Array<{
      icon: string;
      title: string;
      url: string;
    }>
  }

  footer: {
    copyright: string;
    socials: {
      github?: string;
      twitter?: string;
      email?: string;
    };
    style: {
      light: { bg: string; color: string; }
      dark?: { bg: string; color: string; }
    }
  }

  toc: Record<string, string>;
}

The un-edited boilerplate configuration will look like:

seo:

hero:
  style:
    light:
      bg:
      color:
  logo:
    name:
  subheading:
  info_boxes:

toc:

HandyDocs features built-in SEO thanks to the next-seo package. Site metadata such as site name, favicon, open graph info, Twitter info, and more is controlled through the seo part of the HandyDocs configuration file.

The seo part of the HandyDocs configuration file is the most flexible, structure wise. All data included in the seo part of the HandyDocs configuration file is passed to next-seo, which makes it fully customizable.

The hero is the main part of your HandyDocs instance—it's the big, colorful section at the top of this instance. Your HandyDocs instance doesn't have to look quite like this instance, however. HandyDocs offers a variety of customization options to make your instance look exactly the way you want.

The hero part of the HandyDocs configuration file follows a strict structure, represented by the following Typescript interface:

interface HeroConfig {
  style: {
    light: { bg: string; color: string; }
    dark?: { bg: string; color: string; }
  }
  logo: { text: string; }
  subheading: string;
  info_boxes: Array<{
    icon: string;
    title: string;
    url: string;
  }>
}

As you can see, there are a lot of customizable options.

Let's take a deeper look into what each one does.

style

HandyDocs allows you to customize the background and text color of the hero.

• The background can be an image or a color.

  bg: url("/img/hero-bg.png") # image
  bg: "#000" # color
  

  The string that is passed to the bg property will be passed directly to a background CSS property, so any valid CSS background value is accepted.

• The text color can be any color.

  color: "#fff"
  

  The string that is passed to the color property will be passed directly to a color CSS property, so any valid CSS color value is accepted.

You can also customize the hero style for dark and light modes.

light:
  bg: "#fff"
  color: "#000"
dark:
  bg: "#000"
  color: "#fff"

logo

To customize your instance's logo, you will use the logo property. Currently, only text logos are supported, but image support is coming soon!

Simply pass the name of your instance to the logo.name property

logo:
  name: "HandyDocs"

subheading

The subheading is the short description located underneath the logo in the hero.

subheading: "minimal but capable documentation template"

info_boxes

Info boxes are the big links at the bottom of the hero. There are typically 2-5 info boxes in the hero.

The icon of the info box is displayed as a CSS mask, so you can use an SVG image as the icon. Simply place the SVG file in the public folder and link it to the icon property.

info_boxes:
  - icon: "icons/twitter.svg"
    title: "@colegawin_"
    url: "https://twitter.com/colegawin_"
  - icon: "icons/github.svg"
    title: GITHUB
    url: "https://github.com/chroline/handydocs"
  - icon: "icons/git-branch.svg"
    title: 0.0.0
    url: "#"

The footer is found at the bottom of all HandyDocs instances. This is a location for you to conclude your documentation by showing your logo, copyright, and social links.

The footer part of the HandyDocs configuration file follows a strict structure, represented by the following Typescript interface:

interface FooterConfig {
  copyright: string;
  socials: {
    github?: string;
    twitter?: string;
    email?: string;
  };
  style: {
    light: { bg: string; color: string; }
    dark?: { bg: string; color: string; }
  }
}

The footer uses the logo provided in the hero config section.

copyright

Underneath the logo, a copyright message is displayed. The copyright message contains the copyright symbol ©, the current year, and the content you type into the copyright field.

For example,

copyright: "Cole Gawin. Released under MIT License."

will produce

© 2022 Cole Gawin. Released under MIT License.

for the copyright message.

socials

You are able to customize which socials are displayed in the footer and where they link to. Currently, only Github, Twitter, and email socials are supported, but expect more coming soon!

Each social link is optional, and the order in which they are included is the order in which they will be displayed.

socials:
  github: https://github.com/chroline/handydocs
  twitter: https://twitter.com/colegawin_
  email: mailto:hey@colegaw.in

style

HandyDocs allows you to customize the background and text color of the footer.

• The background can be an image or a color.

  bg: url("/img/footer-bg.png") # image
  bg: "#000" # color
  

  The string that is passed to the bg property will be passed directly to a background CSS property, so any valid CSS background value is accepted.

• The text color can be any color.

  color: "#fff"
  

  The string that is passed to the color property will be passed directly to a color CSS property, so any valid CSS color value is accepted.

You can also customize the footer style for dark and light modes.

light:
  bg: "#fff"
  color: "#000"
dark:
  bg: "#000"
  color: "#fff"

Individual sections of a HandyDocs instance are saved as mdx files in the public/docs folder. These files are then imported and processed by HandyDocs.

Each section must be added to the toc section of the HandyDocs configuration file. The toc section is simply an object that maps filenames of the section to their respective titles in the order in which they should be displayed.

For example, if you have 3 sections:

1. Section 1 stored as section1.mdx
2. Section 2 stored as section2.mdx
3. Section 3 stored as section3.mdx

then your toc section would look like:

toc:
  section1: "Section 1"
  section2: "Section 2"
  section3: "Section 3"

---

Content

All HandyDocs content is written in MDX. This means that all standard markdown features are supported, and you can use additional custom components.

Custom components

By default, HandyDocs supports chakra-ui alerts as custom components. If you want to create additional custom components or include more chakra-ui components, be sure to include them in the components object in src/components/Content.tsx.

HandyDocs lets you customize different parts of your instance with custom SCSS styles. Let's run through some examples of what can be customized.

Chakra UI

HandyDocs is powered by chakra-ui, a React component library that allows for a great amount of styling and customization options. Because chakra-ui makes use of CSS variables, you are able to access those variables in your custom styles.

For more information, read the article CSS Variables - Chakra UI on the official chakra-ui documentation.

Fonts

You can customize the global font family used by HandyDocs by setting the --handydocs-font-family CSS variable to whatever font you choose.

html, body, :root {
  --handydocs-font-family: 'Spline Sans', sans-serif
}

Hero

You can add custom styles to the hero by assigning styles to the #hero element.

#hero {
  // styles here
}

Content

You can add custom styles to your content as well by assigning styles to the #content element. Every documentation section contains a div#content element, so your styles will only be applied to within the documentation content.

Here are some custom styles used by the official HandyDocs instance:

#content {
  > * {
    border-radius: var(--chakra-radii-md);
  }
  img, pre {
    border-radius: var(--chakra-radii-md);
  }
  img {
    box-shadow: var(--chakra-shadows-sm);
  }
  pre {
    box-shadow: var(--chakra-shadows-xs);
  }
}

Syntax Highlighting

HandyDocs uses prism.js for syntax highlighting, and as such, you can use any prism.js themes to style your codeblocks. You have the ability to include two separate syntax highlighting themes: one for dark mode, and one for light mode. These files are located at styles/syntax-highlighting/dark.scss and styles/syntax-highlighting/light.scss, respectively.

Simply paste your CSS/SCSS prism.js themes into these files, and your code will be highlighted as desired.