Adding Content

• Header/Navbar
• Sidebar
  • Editing the Sidebar Content
• Documentation Collection
  • Table of Contents
• Locale Files
• Excluding Resources from Search

The first things you may want to do is use your own logo in the header, customize the links there and in the sidebar, add more information to the footer, etc. Or maybe you’ll want to write some pages or blogs posts to get your creativity going. Perhaps you already have some Markdown files and you want to import them and put together a set of documentation.

The great thing is you can design & build your site in any order you choose. Refer to this guide to help steer you in the right direction.

Header/Navbar #

The header/navbar at the top of the layout provides a single row design with a logo, search button, and navigation links to a small handful of destinations. Willamette doesn’t collapse the top navigation system on mobile because it is our belief most sites benefit from as few links as possible in their top nav (while also still showing them on mobile). Further content destinations can flow from a few simple starting points or be related to additional links in the sidebar (see below).

You can customize the logo, control whether the title text also appears (or alternatively, use only title text and remove the logo), and other tweaks by updating the “strategy” object which is set up in the src/_components/shared.rb file within the Navbar component. It’s structured like this:

• logo (String)
• logo_alt (String)
• search (Boolean)
• site_title (String)
• nav_links (Array)

You set either logo or site_title to nil if you just want the other feature to display.

Links are defined within the nav_links array by using the Willamette.link helper. The available options are:

• title (text of the link, set to nil if an icon label is used instead)
• url (relative [internal] or absolute [external] URL)
• icon (the name of the Font Awesome icon)
• icon_family (one of the non-default families available, for example brands)
• icon_label (accessible text, if title is nil)

Only title/icon_label & url are required arguments.

Sidebar #

The left-hand sidebar provides a useful structure, proven on successful websites in production, for a common publishing-style use case:

• A short description
• Social links
• Email signup
• Additional outward-facing links

The nice thing is, this structure is contained within the sidebar template (src/_components/shared/sidebar.erb) in your own repo, so you can redo parts of it or blow it all away and start over. However, it’s also straightforward to fill in your unique content within the existing structure (see below).

The sidebar is collapsed on mobile, accessible via a familiar “hamburger menu” icon near the top of the page (some website designs collapse a sidebar below the main content, which nearly results in that content being invisible to anyone not scrolling down a long ways).

You can also completely switch off the sidebar, either on a per-resource (or per-collection) basis or for the entire site. The sidebar is controlled via front matter:

willamette:
  hide_sidebar: true

If you want to hide the sidebar for an entire collection, you could add a _defaults.yml file at the top-level of your collection folder:

willamette:
  hide_sidebar: true

For hiding side-wide, use front matter defaults in your config/initializers.rb file:

config.defaults << {
  values: {
    willamette: {
      hide_sidebar: true
    }
  }
}

Editing the Sidebar Content #

The sidebar is based on a “strategy” object which is set up in the src/_components/shared.rb file within the Sidebar component. It’s structured like this:

• description (String)
• explore_links (Array, likely autogenerated)
• follow_links (Array)
• subscribe (Boolean)
• see_also_links (Array)

Removing any of these from the strategy instantiation will remove it from the sidebar display (for example, you could take out see_also_links and then that section won’t appear).

Links are defined within the various arrays by using the Willamette.link helper. The available options are:

• title (text of the link)
• url (relative [internal] or absolute [external] URL)
• icon (the name of the Font Awesome icon)
• icon_family (one of the non-default families available, for example brands)

Only title & url are required arguments.

Documentation Collection #

Willamette comes pre-configured with a docs collection. You can add a src/_docs folder to your project and start adding content which will be published under the /docs/ URL. It’s recommended you also add a src/_docs/_defaults.yml file containing layout: documentation so every docs resource will use the documentation layout by default.

  init :willamette do
    # docs will now live in `/guides/`
    docs_url_segment "guides"
  end

The documentation collection is also unique in that you can order all of the resources by using numbered file prefixes, and you can nest related resources inside of subfolders. For example:

src/_docs/
├ 01_index.md # this is your docs entrypoint
├ 10_manual-installation.md
├ 20_adding-content.md
├ 30_customizing.md
├ 30_customizing/
│ └ 10_css-variables.md
└ 40_contributing.md

Willamette will automatically infer the correct order and display the relevant links in the sidebar as well as in previous/next links below each page’s content. The prefix will be stripped from the slug, so src/_docs/20_adding-content is published at the /docs/adding-content URL.

We recommend using three number digits if you anticipate many pages of content, and starting out with leaps of ten so in the future you can insert additional pages without having to re-number many files.

Table of Contents #

To add a Table of Contents sidebar to a Markdown resource in your docs collection (or any collection), you can use the toc helper (which can appear anywhere in your text but probably makes sense right at the top):

<%= toc %>

You can pass a block to include additional Markdown content which will be rendered directly above the ToC in the sidebar:

<%= toc do %>
You can learn _more_ in these **sections**:
<% end %>

Locale Files #

The vast majority of strings used within Willamette templates & components are contained in locale files. You can override these strings both to change the default text and to provide text for additional locales/languages if you’ve set up your site for internationalization (i18n).

To override English strings, create a src/_locales/en.yml file which might look something like this:

en:
  labels:
    subscribe: Sign Up # t("labels.subscribe")
  marketing:
    see_also: Resources # t("marketing.see_also")

You can look through the templates within your site repo to see which strings to update, as well as look through the files in the Willamette gem.

Excluding Resources from Search #

If you’ve kept the Pagefind search functionality enabled from the nav bar, but you want to remove certain resources from being indexed, you can add exclude_from_pagefind: true to any resource’s front matter.