Pico Default Theme

This is the repository of Pico's official default theme.

Pico is a stupidly simple, blazing fast, flat file CMS. See http://picocms.org/ for more info.

Please refer to picocms/Pico to get info about how to contribute or getting help.

Screenshot

Install

You usually don't have to install this theme manually, it's shipped together with Pico's pre-built release packages and a default dependency of picocms/pico-composer.

If you're using a custom theme, you can safely remove this theme.

If you use a composer-based installation of Pico and want to either remove or install Pico's default theme, simply open a shell on your server and navigate to Pico's install directory (e.g. /var/www/html). Run composer remove picocms/pico-theme to remove the theme, or run composer require picocms/pico-theme (via Packagist.org) to install the theme.

If you rather use one of Pico's pre-built release packages, it is best to simply leave Pico's default theme as it is - it won't hurt... 😉 The reason for this is, that the theme is part of Pico's pre-built release packages, thus it will be automatically re-installed when updating Pico. However, if you really want to remove the theme, simply delete the themes/default directory in Pico's install directory (e.g. /var/www/html). If you want to install Pico's default theme, you must first create a empty themes/default directory on your server, download the version of the theme matching the version of your Pico installation and upload all containing files (i.a. index.twig) into said themes/default directory (resulting in themes/default/index.twig).

The versioning of Pico's default theme strictly follows the version of Pico's core. You must not use a version of the theme that doesn't match the version of Pico's core (e.g. version 2.0.1 is not compatible with Pico 2.0.0). If you're using a composer-based installation of Pico, simply use a version constaint like ^2.0 - picocms/pico-theme ensures that its version matches Pico's version. Even if you're using one of Pico's pre-built release packages, you don't have to take care of anything - a matching version of the theme is part of Pico's pre-built release packages anyway.

Usage

Pico's default theme isn't really intended to be used for a productive website, it's rather a starting point for creating your own theme. Simply copy the theme's directory (themes/default/ to e.g. themes/my_theme/) and add the following line to your config/config.yml:

theme: my_theme

You can now edit the theme's stylesheets and JavaScript to fit your needs. If you rather want to use a third-party theme, simply add the theme's directory to your themes/ directory (e.g. themes/some_other_theme/) and update your config/config.yml accordingly. Pico's default theme is now completely disabled and won't ever interfere with your custom theme or your website in general anymore. If you want to use Pico's default theme again, either remove the line or replace it by theme: default.

Anyway, since Pico's default theme is meant to be a starting point for your own theme, it demonstrates how themes can allow one to tweak a theme's behavior. For this reason it supports a "Widescreen" mode: By adding theme_config.widescreen: true to your config/config.yml, the theme's main container grows from 768px to 1152px breadth due to adding class="widescreen" to the website's <body> element. Pico's default theme furthermore supports displaying both a logo and a tagline in its header, as well as adding social buttons to its footer. Rather than using Pico's config for this, it uses the YAML Frontmatter of the content/_meta.md Markdown file. Here's content/_meta.md from Pico's sample contents:

---
Logo: %theme_url%/img/pico-white.svg
Tagline: Making the web easy.
Social:
    - title: Visit us on GitHub
      url: https://github.com/picocms/Pico
      icon: octocat
    - title: Join us on Libera.Chat
      url: https://web.libera.chat/#picocms
      icon: chat
---

You should also check out the theme's pico-theme.yml: First of all it tells Pico to use the latest API version for themes and adjusts Pico's default Twig config. But more importantly it also registers the mentioned widescreen theme config as well as the meta headers Logo, Tagline and Social.

Getting Help

Please refer to the "Getting Help" section of our main repository.

Contributing

Please refer to the "Contributing" section of our main repository.

By contributing to Pico, you accept and agree to the Developer Certificate of Origin for your present and future contributions submitted to Pico. Please refer to the "Developer Certificate of Origin" section in the CONTRIBUTING.md of our main repository.

Titleless pages being hidden is a paper cut.

This was brought up in picocms/picocms.github.io#51, but that thread has gone off topic, so I'm moving the issue here.

The behavior of hiding titleless pages in navigation is a paper cut for new users. It's not documented anywhere, and overall feels more like an oversight than an intended behavior.

From a birds-eye view, it makes sense to hide pages without titles to avoid outputting empty <a> tags.

But in practice this means that a user who forgot their title is left wondering where their page is. Also, it gives users an impression that removing your title is an intended way to hide a page (rather than using Hidden, which isn't actually documented at the moment, as far as I can tell).

While this could be a simple addition to the Docs (picocms/picocms.github.io#51), telling users not to forget their title, I don't really feel like this was an intended behavior in the first place. Rather, it seems like an oversight of how it could affect users (because again, there's already an intended way to hide pages, so this behavior feels confusing).

The simplest way to change this could be to fall back on using page.id when there's no title. A ternary statement (? :) could accomplish this with almost no effort, but it does add complexity to the readability of the code. Since readability is a high priority for the Default Theme, I'm a little torn on this, but it seems like the easiest option.

{% for page in pages(depthOffset=-1) if not page.hidden %}
     <li{% if page.id == current_page.id %} class="active"{% endif %}>
          <a href="{{ page.url }}">{{ page.title ? page.title : page.id }}</a>
     </li>
{% endfor %}

Avoiding the ternary statement would require adding a little bit more code, but might be more readable for a new user:

{% for page in pages(depthOffset=-1) if not page.hidden %}
     <li{% if page.id == current_page.id %} class="active"{% endif %}>
          <a href="{{ page.url }}">
               {% if page.title %}
                    {{ page.title }}
               {% else %}
                    {{ page.id }}
               {% endif %}
          </a>
     </li>
{% endfor %}

But either way, I'm leaning more toward changing this behavior itself than adding a warning to the Docs describing a behavior specific to the Default Theme, that both isn't part of Pico's core, and doesn't affect most themes (at least, the ones that we have at the moment).

@PhrozenByte I'm more than happy to make whichever changes, just wanted to get your input first.

picocms / pico-theme Goto Github PK

pico-theme's Introduction

Pico Default Theme

Screenshot

Install

Usage

Getting Help

Contributing

pico-theme's People

Contributors

Stargazers

Watchers

Forkers

pico-theme's Issues

Titleless pages being hidden is a paper cut.

No blog entries visible

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent

Jobs