NotePaper Theme for Pico

February
2nd

NotePaper Theme

by:Maya McDougall


NotePaper Theme

Thank you for using my NotePaper theme for Pico. This theme was originally inspired by the Anarcho Notepad theme for WordPress. This is my first Pico theme, so the coding might be rough in spots, but overall I'm pleased with how it's turned out. If you have any suggestions on how I can improve this theme, or if you discover any bugs, please create a New Issue on GitHub.

If you're viewing this on GitHub, please check out the NotePaper Site for a live example of the theme.

Features

Widgets

The biggest feature I've brought to this theme is Widget Support. By defining a custom meta variable in your markdown files, you can generate themed widgets that run down the right side of the page. There are two types of widgets, named Stickies and Doodles, as well as a third, "disabled" option for those you'd like to hide temporarily. Sticky Widgets are themed as sticky notes, while Doodle widgets are depicted as if they were drawn onto the page. To make a widget, add "Widget: Sticky", "Widget: Doodle", or "Widget: Disabled" to the header of any markdown file in your content folder.

Widgets are organized by Pico's built-in page ordering. If, for example, you sort your content by ascending date, then I would recommend organizing your widgets using date values (Date: 1001, Date: 1002, Date: 1003) to organize your widgets. If you're using alphabetical page ordering, you could order them by changing the metadata names of the widgets to start with letters (A,B,C). If your pages are in descending order, then just reverse the numbering or lettering you use (C,B,A / Z,Y,X / 1003, 1002, 1001 / etc).

The "Doodle" area is 200px wide, and works great for images, just be sure to size them accordingly. If your image is less than 200px wide, you may want to pad the image to 200px or use html + css to center it.

Image locations (or any other paths) within widgets must be defined with an absolute path from your base_url (e.g. "%base_url%/assets/doodle.png"). Because of how Pico imports content, relative paths are not recommend and are known to cause issues. See Pico's Documentation for additional information about file paths.

Like regular pages, widgets can be written in markdown, html, or a combination of the two. Just make sure they end in ".md" (or the file extension you chose in your config) so Pico can find them.

Front Page

I've also included a simple blog-style front page feature. If enabled in your Pico config, the theme will ignore your main index.md. Instead, it will import the first few content files it finds into one long page. Depending on what you've set Pico's "pages_order" setting to be, the front page will be your most recent pages, your very first pages, your first pages alphabetically, or your last pages alphabetically. By default, it will import five pages, though you can change this with a config option.

The Front Page Mode can also have pagination support, allowing you to navigate through multiple pages of results after the initial limit. At present, this feature requires an optional plugin, though this will hopefully change in the future.

There's also a "blog mode" meta variable. If you add "Blog: True" to your meta header, your page will be hidden from the main navigation and only accessible through the front page or first/prev/next/last buttons.

Sub-Navigation

This feature takes a YAML table of contents and generates a sub-navigation for the current page. This table of contents is defined as a meta variable named "toc" in your markdown file. The formatting is simple: Using spaces, indent each item of the toc by the same amount. Tabs will not work, and will cause your page to throw an exception. The key of each item must match the name of its corresponding html anchor, but its value can be anything you want. This value will become the text displayed for your link. You may also have a second level of items, indented further, within another item. The first item of a new level is used to title its parent. In the example below, its key is "_title", but it doesn't matter what you use. Here is an example of the proper formatting, as used in this readme. Note that I added a second level under "installation" for the sake of the example.

toc:
  features: Features
  download: Download
  installation:
    _title: Installation
    step-1: Step 1
    step-2: Step 2
    step-3: Step 3
  upgrade: Upgrading
  configuration: Configuration
  changelog: Changelog
  license: License

Bottom Navigation Links

There are optional navigation links you can enable for the bottom of your page. These are enabled using a custom config option, and are incredibly customizable. There are five links total, First, Prev, Back to Top, Next, and Last. You can set the text or an image for each one, or disable them individually. You can also define a text character or image to use as a separator between them. A set of default images for these buttons is included in NotePaper.

Comments

I've integrated Disqus and Facebook comments into the theme. They can be enabled in your Pico config. There's also an option of whether or not to display them on your front page, and various settings to customize their appearance.

Please note that both Disqus and Facebook pull in a a large number of extra scripts and resources. These extra scripts are part of how these comment systems work, but can have an impact on the performance of your website.

These comment systems also have privacy implications for your users as both (Facebook especially) are known to track users across the web (sometimes even if they are not logged in!). These comment engines are provided as a convenience, however if you feel they might infringe on your users' privacy, simply disable them.

All comments code is contained within an "if" statement in NotePaper's Twig template. Twig is processed on the server through PHP, so if you have comments disabled, no scripts or other resources will be pulled in or sent to your users! This also helps keep NotePaper modular and stops it from being slowed down by disabled features.

Custom Themes

NotePaper has support for full custom CSS themes. These themes reside in "assets/NotePaper_Themes/". NotePaper themes can be defined globally using config options, but can also be assigned on a page-by-page basis using the "Theme" meta variable. The theme defined in your metadata will always overrule the theme defined in your config. You can also set a page to use NotePaper's default theme instead of the one defined in your config. To do this, simply set your metadata theme value to "Default" (e.g. "Theme: Default").

Two sample themes are included with NotePaper:

These themes will be updated with NotePaper in the future, and more may be added as well. Feel free to create your own themes as well. You can even use the one of the sample themes as a base for your own!

The structure of these themes is simple: The theme "name" is just the name of the folder, and your CSS file should be named theme.css and placed inside it. You should place any other assets in the folder as well and access them in your CSS as needed. You can also add an animations.css file if you'd like to support animations. Please note that if animations are enabled, NotePaper will attempt to load this file regardless of whether it exists.

Override Styles

You can override the default CSS styles of the theme by specifying an overriding stylesheet in your Pico config. Your stylesheet will be linked after both NotePaper's default stylesheet and any Theme's stylesheet, so you only need to style the elements you'd like to change.

Override Styles are best used if you have one or two elements that you want to change about NotePaper (or one of its themes). If you'd like to do a major overhaul of its appearance, try creating a custom "NotePaper Theme" instead. This will give you more flexibility when choosing the appearance of your site, and will save the Override stylesheet for when you might need to override a few elements of your own theme.

You can also specify a per-page css override by adding css_override: path/to/override.css to your page's metadata.

Search

NotePaper includes a very basic search function that can search page titles, descriptions, and content for a single search term. At the moment, the search is treated as a solid string, so if you search for multiple words, it will only find them exactly as you typed them.

There is a sample search widget included with NotePaper. You may use it as is, modify it, or create your own version.

The search feature requires the optional plugin in order to function.

Tag Widgets

NotePaper includes two optional, tag-based widgets. These widgets operate by reading a "Tags" meta variable from every page. Tags should be a list of items, separated by commas. Spaces in tag names are not yet supported, but will be added in the future. A properly formatted tag list would look like this: "Tags: One,Two,Red,Blue". Note that even if the tag widgets are enabled, they will not display if no tags are found in your content.

The Tag List widget will display all tags in a list. The Tag Cloud widget will display a block of tags, with more common tags appearing larger than less common tags. Text sizes start at 2em and are reduced from there. You can specify how many size increments to use in your config file.

Both widgets have the option to display the number of occurrences in parentheses next to the tag name. They can be sorted either alphabetically or numerically (by number of occurrences). If you don't specify a sorting method, they'll be displayed in rather chaotically, in the order Pico discovers them (dependent on your Pico config and the order you've written them in). They can also be ordered in reverse order. The heading text of either widget can be specified in the config as well.

Clicking on a tag in either widget will do a search for all pages labeled with that tag.

Folder Navigation (Experimental)

Folder Navigation will break up your Table of Contents into separate widgets based on your folder structure. Pages in the root of your content folder will appear as normal in the Table of Contents. Pages inside folders will be organized into separate widgets based on this first level of folder. Any deeper folders will be rendered as pop-up menus when you hover on their name.

Folder names will be automatically converted into Title Case (allowing you to use lowercase folder names) and any underscores "_" will be converted to spaces. This name converting scheme is hard-coded at the moment, but I will likely add customization in the future.

Download

You can download the NotePaper theme on GitHub.

Installation

Selectively extract the contents of the download into your Pico folder.

Finally, don't forget to update your config.yml to use the NotePaper Theme. This value will probably be case-sensitive on most filesystems, so be sure to match the folder name:

theme: NotePaper

While you're at it, you'll likely want to modify the config options discussed below. They add quite a few levels of extra customization.

Plugin

Several of the features of this theme require the use of a small plugin. The purpose of this plugin is to pass the Query String variables along to Twig, something that Pico does not do by default. This will hopefully change in the future.

The plugin does two things, and only two things. First, it passes on Query String data to Twig in a variable named "TwigGetUrl". Next, it defines a new variable "TwigGetUrlEnabled" as True. This second variable is used to determine whether the plugin is active or not.

There is a small possibility that the use of this plugin could create a security risk. In my tests, I have been unable to break anything with it. I am not a security expert however and do not know all the ins and outs of Pico, PHP, and Twig. As far as I can tell, there should be no added risk to running this plugin, but I unfortunately cannot guarantee this.

In the future, I will be searching for a better way to accomplish these features, hopefully without needing a plugin.

Configuration

Here is a list of all the custom configuration options you can utilize in this theme. The config options are written as YAML, and a sample file is provided for ease of use. Also, please note that date_format is now ignored in this theme. The date format is instead hard-coded to work around the lack of ordinal suffixes in strftime (used by Pico 0.9 and later).

site_logo

If this variable is defined, your site's title will be replaced with this image file. It must be defined as an absolute path from your base_url (e.g. "assets/site_logo.png").

og_image

"Open Graph" Image. You can specify an image to be used when sharing a link on Facebook and other sites that support it. Since this theme has a dark background by default, this provides a nice workaround for light logos not displaying against Facebook's white background. You can use Facebook's Debugging Tool to help diagnose any issues using this feature.

copyright

This text string will be displayed in the footer of your website.

description_length

The Search and Tag views use meta.description for listing search results. Here, you can define the character length of automatic descriptions for files that are lacking a meta.description. The automatic descriptions will be rounded down to the previous space so as to not truncate any words. An ellipsis is also added to the end of the description.

css

toc

Table of Contents. This is the text that will display above your navigation (the sticky note in the top right).

Experimental Folder Navigation. If enabled, your Table of Contents will be broken up into categories based on your folder structure.

tags

front_page

comments

bottom_links

disable

Upgrading

If you're upgrading from a previous version of NotePaper, the best way to upgrade is to backup and replace your old NotePaper.yml file with the new version and then migrate your old config values into the new fields.

This is because NotePaper is constantly improving and the structure of NotePaper's config is continuously changing to make room for new options and to refine old ones. Replacing the old file with the new one ensures that any changes made since the last version will not cause problems for your website.

All other NotePaper files can just be removed/replaced as usual. You may want to remove your old NotePaper files first, just in case some of them have moved around since the last version.

Changelog

1.5.5 - 02/17/21

1.5.4 - 02/02/17

1.5.3 - 05/01/16

1.5.2 - 03/18/16

1.5.1 - 03/10/16

Fixed two minor papercuts:

1.5.0 - 02/29/16

1.4.0 - 12/03/15

1.3.2 - 10/31/15

1.3.1 - 06/19/15

1.3.0 - 06/19/15

1.2.0 - 06/12/15

1.1.0 - 06/06/15

1.0.0 - 06/05/15

License

This theme is free software under the terms of the GNU General Public License v3. Please see the included LICENSE file for details.

Please use and/or modify it as you see fit.

You may also comment out the author credit text in the footer of the page if you feel it interferes with your website.