Submitting your theme or plugin for inclusion on the website is very easy.
We’ve written some guidelines here to walk you through the process.
Found a typo? Something is wrong in this documentation? Just fork and edit it!
Submitting content to the website is easy, all you have to do is create a new Pull Request on GitHub. To make the submission process smoother, our themes and plugins pages are dynamically generated using a collection of Markdown files. The guidelines on this page will explain the layout and structure of those files.
And if, for whatever reason, we don’t feel that your submission is up to par, we’ll work with you to improve it.
Pico’s website is found in the
picocms.github.io repo on GitHub. In this repo, you’ll find two folders named
_plugins. These folders contain all the individual files that make up the themes and plugins pages respectively.
Each item has three types of files:
fullsize screenshot of your item.
thumbnail screenshot of your item.
Here’s an example of how we keep these files organized:
│ ├── images
│ │ ├── fullsize
│ │ │ ├── plugin_1.png
│ │ │ ├── plugin_1-2.png
│ │ │ └── plugin_2.png
│ │ └── thumbnails
│ │ ├── plugin_1.png
│ │ └── plugin_2.png
│ ├── plugin_1.md
│ └── plugin_2.md
│ ├── fullsize
│ │ ├── theme_1.png
│ │ ├── theme_1-2.png
│ │ └── theme_2.png
│ └── thumbnails
│ ├── theme_1.png
│ └── theme_2.png
Each section, themes and plugins, has an
images is further separated into
thumbnails folders. It’s pretty self explanatory that fullsize and thumbnail images should go in their respective folders.
Our recommended naming convention is to name all three of your files (the markdown and the two images) with the same name, but their respective extensions. In the previous section’s example, this would be
thumbnails/theme2.png. Any additional
fullsize image names should start with this name, but you are free to add your own variation to distinguish between them (
theme2-2.png, etc.). This naming convention will help us and others to better identify which images belong to which item.
For your image format, we’d ask that you pick whichever format best optimizes your image size vs. its quality. If your image has large blank or simplistic sections, a
.png image will provide the best quality at a reasonable file size. If your image is busy or has a lot of fine detail, we’d recommend you using a
.jpg with a slightly reduced quality (80-95% should provide a good balance). If you’re unfamiliar with the differences between these formats, you can experiment to determine which option will provide the best balance of quality and file size. If you have any questions, we are here to help.
For thumbnail images, you should use a resolution of 270x220 px. The thumbnails are a locked size on the website, so providing a different aspect ratio will result in your image being squashed.
Fullsize image resolution isn’t as strict. These images will be proportionally scaled to the right size. We do however recommend a resolution of at least 1440x900 px, as these images can be viewed fullscreen by clicking on their magnifying glass icon.
Your screenshots should match the following specifications:
ProTip: You can use Firefox’s Responsive Design Mode or Chrome’s Device Mode to quickly take screenshots in your desired resolution. For thumbnails, we’d sugguest taking a 1080x880 px screenshot, then scailing it down to 270x220 px in your favorite editor.
The name of your theme or plugin.
The absolute location of your thumbnail image. See the “Screenshot Specifics” section above for more information.
These categories are displayed along the top of the page. By clicking them, you can filter the results to just those of the category. Each category below has a special short-name to use in your YAML. We may add more categories in the future (let us know if you have any suggestions).
single-page) - A single page website, where all content is displayed on the
portfolio) - A theme intended to be used as a portfolio of your work or to establish an online presence on your personal domain.
blog) - A theme styled with blogging or news posts in mind.
admin) - A plugin that adds administration capabilities to Pico.
utility) - A plugin that offers more developer-focused functionality.
theming) - A plugin that extends Twig by adding extra variables or functionality to your templates.
A short, one-line, description of your theme/plugin that displays below its title.
The URL of the “Learn More” button.
Specify custom text for the “Learn More” button. This is an optional value, not included in the example below. We don’t recommended changing this text, so be ready to convince us as to why you feel the change is necessary.
This is a list of your
fullsize images. Specify the absolute location of each image. See the “Screenshot Specifics” section above for more information.
Here you can specify a few lines of “info” that will display above your description. Each item must at least give information about its license using the
License item. We furthermore recommend adding a
By item, but you can create your own items if they’d better fit the context of your theme or plugin.
If your entry is a port of someone else’s work, please use the
Ported By and
Original By lines instead of the regular
By. We’d like to make sure that the original content creators receive proper credit for their work.
Also, as visible in the template below, you can add links to these
info items. You can easily link your
By line to your GitHub profile or another location. If you’re using the
Original By line, you should also link to the original source in this manner. You can use either HTML or Markdown links, but if you use Markdown, you’ll want to wrap the entire string in quotes. This is because the
 characters have a special meaning in YAML and must be escaped.
You can also use
_ as the first character of your item’s identifier to create a line without a visible identifier. For example, using
_item: An Example Message would simply display “An Example Message”. You can have several of these lines, as long as they have unique names.
Finally, your main content should go after the YAML Frontmatter, in the Markdown body. This content can be as long as you’d like, but keep in mind that, for themes, the content area is very narrow (it’s roughly 40 characters wide). Plugins are given a much larger space for their content.
The following code block is a template for your submission’s
.md file. Copy and paste this section into your document and edit it to create your submission.
heading: My Theme or Plugin
description: A short description for the hover text.
# - themes/images/thumbnails/my_theme_or_plugin-2.jpg
# - themes/images/thumbnails/my_theme_or_plugin-3.jpg
By: "[The Octocat](https://github.com/octocat)"
# Ported By: "[The Octocat](https://github.com/octocat)"
# Original By: "[Someone Else](https://example.com/)"
License: "[The MIT License](https://opensource.org/licenses/MIT)"
This is my theme for Pico.
Or maybe it's a plugin...
Either way, if it really existed, this is where I would write some details about it.
So you’ve read all of our Guidelines and you’re ready to make your submission. What now?
For those unfamiliar, there are many ways to interact with Git and GitHub. For simplicity, we’ll be covering the command line version of Git, but there are many graphical Git clients as well. For those on Mac and Windows, you can check out GitHub Desktop, GitHub’s official Git client.
If you’re new to Open Source, or haven’t contributed to a project before, we’d also recommend checking out GitHub’s “Contributing to Open Source on GitHub” guide.
Finally, GitHub also provides an excellent overview of the process we’re about to embark on. Check out their guide on forking projects to learn all you’ll need to know.
Don’t forget, we’re here to help! See our “Getting Help” section for assistance, and don’t be afraid to contact us.
Fork - Ready to go? You can start by creating a Fork of our Git Repository on GitHub. To do this, visit our website’s source code on GitHub and click the “ Fork” button in the top right. You will of course need to have a GitHub account to do this.
Clone - Next you need to Clone your new Repository down to your local machine. From the command line, this would be:
git clone https://github.com/YOUR USER NAME/picocms.github.io.git
Make Changes - Now, create your submission using the information we provided above. Remember, themes go in
_themes, while plugins go in
Commit - Once you’re done, you can Commit your changes to your local Git Repository using the following command. Remember to replace
YOUR SUBMISSION NAME with the actual name of your submission.
git commit -am "Submission: YOUR SUBMISSION NAME"
Push - Finally, Push your Commit back up to your GitHub account with:
Pull Request - Back on GitHub you’ll need to create a Pull Request. Click the
New Pull Request button, give your PR a name and a brief description and finally click
Create Pull Request.
We’ll take it from there. Be sure to check back and see if we have feedback or changes to request.