Skip to content

Latest commit

 

History

History
355 lines (257 loc) · 13.7 KB

README.md

File metadata and controls

355 lines (257 loc) · 13.7 KB

Neon Jekyll Components

Some Liquid components which can be used in Jekyll, for use in the Neon theme system.

Dependencies

This repo only contains renderers for HTML code. As such, it assumes you will be using the Neon stylesheet system to render these components. This can be utilized simply by importing the following as normal CSS stylesheets:

Additionally, these are recommended:

Of course, if you prefer, you can use any stylesheet you want, including making your own.

Components

This repo contains the following components, usable as Jekyll/Liquid includes. The documentation below uses some symbols to help it remain compact:

  • 👇🏽 - The argument can be placed directly in the include's arguments
  • 📄 - The argument can be specified in the page's front-matter
  • 🌐 - The argument can be specified in the site's config

This is also the precedence order: The top items in this list take precedence over following ones. If two or more are specified, the highest one is used.

App Bar

App-Bar/app-bar.html The app bar is modeled after the Material app bar (Top).

Arguments

Argument Description Allowed values
👇🏽📄 `title` The text shown in the app bar as the page title

  • Any string: The given string is blindly placed in the app bar
_optional_
👇🏽📄 `navigation-back` 		Whether to provide a "Back" button in the app bar. This can be specified in the page front matter, or as an include argument. If both are specified, the include argument take precedence.

  • Excluded or false: A "Sidebar" button appears instead

  • true: A back button appears in place of the sidebar button, using JavaScript to navigate back. If JavaScript is disabled, this navigates to the site root ("/")

  • Any string: A back button appears which navigates to the given string, blindly placing it in the href field.
_optional_
👇🏽📄 `subtitle` 		A subtitle to show in the app bar

  • Excluded or false: No subtitle appears

  • Any string: The given string is blindly placed in the app bar next to the title

Sidebar

Sidebar/sidebar.html The sidebar is modeled after the Material navigation Drawer

All site config variants to these must be nested under a sidebar YML object, like this:

sidebar:
    headerImage:
        url: https://example.com/sidebar-header.png
        htmlClassNames: "greyscale square"

Arguments

Argument Description Allowed values
_optional_
👇🏽🌐 `emptyHeader` 		Whether to leave the header of the sidebar empty (no image). If specified via the site config, then it must be nested as `sidebar.emptyHeader`. If not specified, then `headerImage_url` must be specified (see below).

  • Excluded or false: The header image is displayed, or an error message if none was specified

  • true: The header image is not displayed at all
_optional_
👇🏽 `headerImage_url`
🌐 `headerImage.url` 		The URL to the image to display in the sidebar's header. If excluded, then `site.author.avatar` will be used. If that configuration isn't set, then `emptyHeader` must be specified. - Excluded or `false`: The header image is the author's avatar, or is not displayed. If `emptyHeader` is not `true`, then an error message is displayed instead, to ensure that this is on-purpose. - Any string: The URL to the header image 
</td>
_optional_
👇🏽 `headerImage_htmlClassNames`
🌐 `headerImage.htmlClassNames` 		Any classnames to place in the `class` attribute of the HTML element representing the header image.

  • Excluded or false: No additional classname is applied to the HTML element representing the header image

  • Any string: The given string is blindly inserted into the HTML element's class attribute
_optional_
👇🏽🌐 `excludeHomepageLink` 		Whether to exclude the homepage link from the sidebar.

  • Excluded or false: The link will appear. When the user is on the homepage (/), this link still appears but is disabled

  • true: The link is not displayed at all
_optional_
👇🏽🌐 `excludeAboutLink` 		Whether to exclude the about page link from the sidebar. The name of the about page is specified in the site config as `pages.about`; if that's not specified, it's assumed to be `about`, with the path `/about/`.

  • Excluded or false: The link will appear. When the user is on the about (e.g. /about/), this link still appears but is disabled

  • true: The link is not displayed at all
_optional_
👇🏽 `links` 		Page-specific links to place in the sidebar

  • Excluded or false: Only site-wide links are placed in the sidebar

  • Array of objects: The links to place in the sidebar beneath the site-wide links. Here are the object fields:

    • url: The URL to which the link directs. Can be a javascript: URL
    • materialIcon or fontAwesomeIcon: optional - The icon to use next to the link text
    • text: The text to display in the link
_optional_
👇🏽 `additionalSectionIncludes` 		Any additional sections to place below the links in the sidebar.

  • Excluded or false: No additional sections are placed in the sidebar

  • Array of strings: Paths to any liquid files to {% include %} in the sidebar

Jump Pills

Jump-Pills/jump-pills.html A collection of pill-shaped buttons which serve to allow the user to jump to different parts of the page.

Arguments

Argument Description Allowed values
👇🏽 `ids` The `id`s of elements on the page

  • Array of objects: An array containing the ID and text for each jump pill. Here are the object fields:

    • id: The ID of the page element which this pill jumps to
    • title: The text to place in the pill

Galleries

Some image galleries

Thumbnails

Galleries/thumbnails-gallery.html A grid of thumbnail images and a caption

Arguments

Argument Description Allowed values
👇🏽 `images` The images to display in the gallery

  • Array of objects: The images to show in the gallery. Here are the object fields:

    • thumb: optional - The URL to a small version of the image, to show the user in this gallery before they've selected it. If excluded, the full-size image is resized to work as the thumbnail, after being sent to the user in full.
    • full: The URL to the full version of the image, which will be shown if the user selects the thumbnail
    • alt: optional - Metadata text to include with the image, which will be shown if the thumbnail fails to render for any reason, and which will be read by screen readers.
_optional_
👇🏽 `caption` 		The text to display at the bottom of the gallery

  • Excluded or false: No caption is placed in the gallery

  • Any string: The given text is be placed at the bottom of the gallery

Single-Item Highlight

Galleries/single-item-highlight.html A "gallery" which only highlights one single item.

Arguments

Argument Description Allowed values
👇🏽 `full` The URL to the full-size version of the item

  • Excluded or false: The gallery is rendered "flat" - it has no effect to indicate it has higher priority than other galleries

  • true: The gallery is rendered as "raised" - it has an effect applied to indicate it has a higher priority than other galleries.
_optional_
👇🏽 `thumb` 		The URL to a small version of the image, to show the user in this gallery before they've selected it

  • Excluded or false: The full-size image is resized to work as the thumbnail, after being sent to the user in full.

  • Any string: The given text is used as a URL to a small version of the image, to show the user in this gallery before they've selected it
_optional_
👇🏽 `alt` 		Metadata text to include with the image, which will be shown if the thumbnail fails to render for any reason, and which will be read by screen readers.

  • Excluded or false: The image has no alt text metadata

  • Any string: The given text is used as the image's alt text
_optional_
👇🏽 `caption` 		The text to display at the bottom of the gallery

  • Excluded or false: No caption is placed in the gallery

  • Any string: The given text is be placed at the bottom of the gallery
_optional_
👇🏽 `small` 		Whether to render the gallery smaller than normal.
This relies on an external CSS stylesheet to render galleries with the `small` class differently than others.

  • Excluded or false: The gallery is rendered in its normal size

  • true: The gallery is rendered smaller than normal
_optional_
👇🏽 `raised` 		Whether to render the gallery as a raised or flat card.
This relies on an external CSS stylesheet to render galleries with the `raised` class differently than others.

  • Excluded or false: The gallery is rendered "flat" - it has no effect to indicate it has higher priority than other galleries

  • true: The gallery is rendered as "raised" - it has an effect applied to indicate it has a higher priority than other galleries.
_optional_
👇🏽 `float` 		Whether the gallery should [float](https://developer.mozilla.org/en-US/docs/Web/CSS/float) in the page flow.
This relies on an external CSS stylesheet to render galleries with the `left` and `right` classes differently than others.

  • Excluded, blank, or false: The gallery is not floated

  • left: The gallery is floated to the left

  • right: The gallery is floated to the right

Single-Item Highlight (Custom)

Galleries/single-item-highlight-custom-start.html and Galleries/single-item-highlight-custom-end.html A "gallery" which only highlights one single item, and allows you to place anything at all in the gallery (for example, a YouTube video).

This requires you include the start, then place your custom content, then include the end.

Arguments for start

Argument Description Allowed values
_optional_
👇🏽 `raised` 		Whether to render the gallery as a raised or flat card.
This relies on an external CSS stylesheet to render galleries with the `raised` class differently than others.

  • Excluded or false: The gallery is rendered "flat" - it has no effect to indicate it has higher priority than other galleries

  • true: The gallery is rendered as "raised" - it has an effect applied to indicate it has a higher priority than other galleries.

Arguments for end

Argument Description Allowed values
_optional_
👇🏽 `caption` 		The text to display at the bottom of the gallery

  • Excluded or false: No caption is placed in the gallery

  • Any string: The given text is be placed at the bottom of the gallery