About this theme

This theme is called "pach-emdash" and lives in /themes/pach-emdash.

Theme Directories

`/archetypes`

Archetypes are an optional way to generate markdown files based on defined templates. This is not currently set up in our Hugo project.

`/assets`

The assets directory is for resources that you intend to transform (minify, optimize, etc) such as CSS, javascript, etc. For static assets, see the Static section.

You can reference assets in your layouts like so:

{{ $toc := resources.Get "js/toc.js"  | resources.Minify  }}
{{ $clippy := resources.Get "js/clipboard.js"  | resources.Minify }}
{{ $relatedArticles := resources.Get "js/relatedArticles.js"  | resources.Minify }}
{{ $darkMode := resources.Get "js/darkMode.js" | resources.Minify   }}
{{ $notices := resources.Get "js/notices.js"  | resources.Minify  }}

{{ $js := slice  $darkMode $toc $clippy $relatedArticles $notices | resources.Concat "js/bundle.js"}}

<script src="{{ $js.RelPermalink }}" ></script> ## result

`/css`

The CSS assets used in this theme is powered by Emdash. This is a framework I'm building aimed at helping writers build content-first layouts.

Almost everything has been converted into variables that you can modify from :root instead of having to change the css directly (spacing, line height, colors, font sizes, etc).

`/js`

The JS assets in this theme are hand-rolled; the less dependencies there are, the faster your site will build, load (PageSpeed score), and the easier it will be to collaborate with people who have different machines. If you find this JS is not efficient, please say so and optimize it -- but try to avoid adding dependencies.

algolia.js: Powers search on all pages except the landing page
algoliaHomePage.js: Powers search on just the home page (index.html default layout)
clipboard.js: Powers copy-to-clipboard functionality on code/pre blocks
darkMode.js: Powers dark/light mode toggle functionality
filterByTags.js: Powers the search.html and 404.html tag-based search functionality
keyboard.js: Enables moving through articles using your arrow keys; currently WIP.
mermaid.js: Enables using standard code blocks for mermaid diagrams (just pass the mermaid lang)
notices.js: Enables dismissing notices by clicking the (x)
pagination.js: Powers pagination UI on pages using the glossary.html layout
relatedArticles.js: Powers the related articles toggle on pages using the single.html layout
tables.js: Wraps content tables in a div with overflow-x: scroll.
tagResultsFilteredByVersion: Filters the list of pages on a tags/ view to only those matching the ?&v= URL parameter value.
toc.js: Powers the table of contents / scroll highlight on pages using the single.html layout

`/layouts`

Layouts are ordered and generated by Default > Partials > Shortcodes.

Shortcodes are not used in layouts themselves; they are used in markdown files.

`/default`

Contains base layout templates that define the broader shape of the content.

These templates reference partial layouts and "blocks." Blocks are named placeholder-wrappers that allow higher-level layouts to be inserted into their lower-level layout counterparts during site generation.

Blocks are placed in lower-level layouts with:

{{block "<blockName>"}} {{end}}

And defined in higher-level layouts with:

{{define "<blockName>"}} <html, templating, text> {{end}}

`/_markup`

Contains the render-heading.html layout which is responsible for looping over h1-h6 and adding anchored links during the build process.

Default Templates

Layout	Partials Used	Description
Baseof	head, nav, algoliaHits, directory, footer, featureBreadcrumbs, feaureEditLink, featureKeyboard, featureTags	Contains the opening and closing HTML tags; wraps around the `glossary`, `list`, `search`, `single`, `section`, `series`, and `404` layouts (which are passed in through the `main` block).
Index	featureCommunityDetails,	Minimalist google-inspired search landing page with custom search UI.
Glossary		A standalone default layout for showing child pages as a scrollable stack. To use this layout, define layout: glossary on the parent page of any collection you wish to view as a glossary. Using the glossary layout hides the children from the directory file tree (the assumption being way too many entries will show up and distort your directory.)
List	utilityVersionNumber	Auto-generated pages like taxonomy pages and the default home page (/index.html) are considered list pages. You can create a unique home page by defining a index.html template in your layouts folder.
Search		WIP exploration dashboard that reveals articles by selected tag filters.
Section	featureBetaNotice, featureChildPages	A default layout for parent pages (_index.html). This layout defines the main block placed in the baseof template and shows child pages as cards that include a title, a page count, and a summary.
Series	featureBetaNotice	A taxonomy-specific layout for the custom taxonomy key series. This layout aggregates the tagged pages and displays a single, scrollable view. Use the seriesPart front matter field to order your series from 0-999.
Single	featureSeriesButton, featureBetaNotice, featureNextPrev, featureGiscus	A default layout for standard pages that have no children/descendants. This layout defines the `main` block placed in the `baseof` template.
404		Displays the search dashboard when met with a 404.

`/partials`

Partial layouts (/themes/<themeName>/layouts/partials) are reusable components placed in _default layouts. For this theme, partials prefixed with feature can be hidden or displayed by editing their global feature flag in the config.yaml file.

Default feature config:

params:
  # Feature Switches #

  ## Branding features
  logos:
    footer: "/../images/footerLogo.svg"

  ## Content features
  childPages: 
    display: true # displays child pages of a section.
    grandchildren: true # displays first 7 grandchildren as buttons in the card.
  editLink: 
    display: true #  displays a link to the corresponding github file for a given page; githubUrl must be set.
    githubUrl: https://github.com/pachyderm/docs/tree/main/content/  # should end with content/ 
  giscus: true # displays giscus commenting on single pages.
  heroBanner:
    single: true # displays hero section with a background image, title, description, and date on single pages.
    section: true # displays hero section [...] on section pages.
    list: true # displays hero section [...] on list pages. 
    glossary: true # displays hero section [...] on glossary pages (layout:glossary frontmatter). 
  relatedArticles: true # displays related content on page.
  seriesButton: true #  displays a "Read the <> series" button at the bottom of a page with series frontmatter.
  toc: true #  displays a table of contents in a page; can be overridden by individual page settings. (WIP)

  ## HomePage Features
   # TODO: add date sort to range on featureDisplayVideos
  Videos: false # displays first 3 videos from "/tutorials/videos/", sorted by date.
  CommunityDetails: true  # displays slack and other community details (WIP)
  
  ## Release Features
  versionDropdown: true # displays a top-nav dropdown with top-level sections served as versioned documentation. 
  downloads: true # Enables displaying the download dropdown (requires release.patch)
  releaseInfo:
    latest: "2.3.x" # displays matching directory's sections on home page; if blank, all directories are displayed.
    patch: "2.3.2" # Used to generate download links


  ## Nav features 
  navLevel: true  #  displays level-2 directory items in the file tree.
  breadcrumbs: true # displays a trail of breadcrumbs
  nextPrev: true #  displays the next and previous article available on single page.

  ## Testing Features
  defaultCss: false # displays default bulma css only without branding.

`/shortcodes`

Shortcodes are reusable components that style content/data from the markdown (.md) file itself. This is useful for injecting callouts, quizzes, iframes, and highly-referenced information while keeping only one source of truth.

As a best practice, keep your content-driven shortcodes in a /content subdirectory, and your data driven-shortcodes in a /data subdirectory.

Hugo comes with a few pre-built shortcodes, such as support for GitHub Gists, Youtube Videos, Vimeo Videos, Tweets, Figures, and more.

Custom Shortcodes

Shortcodes are powerful because of their flexibility and ease of use. Below is our notice.html (callout) as an example:

{{$type := .Get 0 }}

<section class="rounded-1 {{with $type}} {{.}} {{else}}darken-3{{end}} sp-1"> 
<div class="spread-between">
    <div class="is-fit l mt-1">{{if eq $type "warning"}}⚠️{{else if eq $type "info"}}📖{{else if eq $type "tip"}}💡{{else if eq $type "danger"}}☠️{{else if eq $type "example"}}✍️{{else if eq $type "success"}}🎉{{else}}ℹ️{{end}}
    </div>
    <button class="is-fit darken-1 sp-1 rounded-3 uppercase xxs hide">toggle</button>
</div>
<div class="content">
    {{ .Inner }}
</div>
</section>

Define the html and css; in this case a div with Emdash classes.
Define the templating details:
- {{ .Get 0 }} passes in the first argument of the shortcode as a string
- {{.Inner}} passes the wrapped markdown content.

{{% notice tip %}}
My inner text is here! Supports markdown formatting.
{{% /notice %}}

In this case, tip is the first argument; it is a CSS class created to style the div. You can pass multiple arguments to a shortcode, and even use the page's frontmatter or site's global variables.

`/static`

The static folder should contain only theme assets that you do not need or want to transform; default images/svgs, fonts, etc. These static assets are served directly from the /images path of your site.

Note: Your theme's static folder is different from your site's static folder; you can also store static assets from a top-level /static folder.

SEO

OpenGraph

Uses default internal Hugo template {{ template "_internal/opengraph.html" . }}
Found in /themes/pachyderm/layouts/partials/head.html

Robots.txt

Enabled by enableRobotsTXT: true in config.yaml
Template is found in /themes/pachyderm/layouts/robots.txt
Disallows following links on older release pages

Default Template

{{range after 2 .Site.Sections.ByTitle.Reverse}}

    {{range .Sections}}

    Disallow: {{ .RelPermalink }}

        {{ if .Pages}}

            {{range .Pages}}
    
                Disallow: {{ .RelPermalink }}
    
            {{end}}
        
        {{end}}

    {{end}}

{{end}}

Twitter Cards

Uses default internal Hugo template {{ template "_internal/twitter_cards.html" . }}
Found in /themes/pachyderm/layouts/partials/head.html

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

About this theme

Theme Directories

`/archetypes`

`/assets`

`/css`

`/js`

`/layouts`

`/default`

`/_markup`

Default Templates

`/partials`

`/shortcodes`

Custom Shortcodes

`/static`

SEO

OpenGraph

Robots.txt

Default Template

Twitter Cards

Files

README.md

Latest commit

History

README.md

File metadata and controls

About this theme

Theme Directories

/archetypes

/assets

/css

/js

/layouts

/default

/_markup

Default Templates

/partials

/shortcodes

Custom Shortcodes

/static

SEO

OpenGraph

Robots.txt

Default Template

Twitter Cards

`/archetypes`

`/assets`

`/css`

`/js`

`/layouts`

`/default`

`/_markup`

`/partials`

`/shortcodes`

`/static`