Creating Content in Pico

Simple But Elegant Content Management

Pico’s flat file nature is a simple approach to content management. Pico has no dashboard or admin panel. There’s no clunky interface for creating posts or pages.

In all their efforts to be all-in-one solutions, many CMS’s provide an overwhelming amount of options, metadata, interfaces within interfaces, and other overhead to worry about.

Pico is simple: You just create a file and write.

The Content Folder

Let’s start with the most basic question, “Where do I put my content?”.

In Pico, your website’s pages are created from Markdown (.md) files, which live in your content folder.

Publishing a new page to your Pico site is as simple as dropping a new .md file in this folder. You can even organize your pages into subfolders if you’d like.

Pages get their URL from their path and filename, so keep this in mind when naming and organizing them.

You’ll want to start with an index.md file which will act as the landing page for your site. We’ll dive deeper into creating those pages soon.

Keep in mind, the content folder is for Markdown only. If you’re using our recommended webserver configuration, this folder won’t be accessible to the outside world. We’ll go over where you can put the rest of your assets in a bit.

The Sample Contents

You’ll notice when you first navigate to your Pico site that there’s already content here, even though you haven’t added anything to the content folder.

You’ve just discovered the Sample Contents! Pico includes these pages internally and displays them whenever your own content is missing. Don’t worry, as soon as you add your own index.md to the content folder, Pico will automatically switch to displaying your content instead of its own.

The Sample Contents can also be a quick reference for what content files should look like. You can view the source for these files on GitHub. Just be sure to enter the Source View of the files with the < > button, as GitHub defaults to showing you the Rendered Markdown content.

Also contained within the Sample Content is a Theme Styling Test page you might find useful if you decide to create your own Pico Theme.

All About URLs

When using Pico, each one of your Markdown files gets a URL based on its folder path and filename. Inside the content folder, a file named about.md would have a url like example.com/about, while a file at projects/my-awesome-project.md would be viewable at the url example.com/projects/my-awesome-project. Pretty simple, right?

These URLs are examples with URL Rewriting enabled. Without it, they’ll have a question mark ? in them after the root address, like example.com/?about and example.com/?projects/my-awesome-project.

Your index.md always acts as the root / of your website. It’s the page you see when you navigate to example.com.

Subfolders can also have an index.md if you’d like. You can put the index page for your subfolder at either subfolder.md or subfolder/index.md. Pico will turn either file location into example.com/subfolder/, however Pico will prioritize subfolder/index.md if both files exist! Use whatever location works best for you.

Now that you know how Pico generates urls, let’s learn how to actually create that content!

YAML and Markdown

YAML and Markdown are a common pair in today’s world, possibly due to the popularity of GitHub. YAML provides an easy to understand syntax for your pages’ metadata while Markdown provides easy, plain-text formatting of your content. The pair make a great combination, and once you learn them you’ll find it hard to disagree.

YAML - Yay, A Metadata Lesson

Writing your metadata in YAML is as easy as writing it out. Each of your content files in Pico will begin with a “YAML Header”. It will look something like this:

---
Title: Welcome
Description: Welcome to my website, where we discuss the finer points of Pico.
Author: Joe Bloggs
Date: 2013/01/01
Robots: noindex,nofollow
Template: index
---

Simple, huh? And it gets better too. These are all the variables that Pico supports by default, but none of them are required for your page to work. The only “required” item on the list above is “Title”, because Pico’s Default Theme uses the page Title in order to link to it.

Each of these metadata fields are utilized by your Pico theme. Some themes may add or require additional fields in order to function. We’ll go into that in more detail about these when we discuss Theming with Twig. For now, stick with Title, Description, Author, and Date, as these are things most pages should probably have.

Markdown - Because Why Mark Up?

Markdown makes formatting your pages simple and intuitive. According to its creator, John Gruber, “Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).”

Sounds good, right? When writing your Pico content files, you get to use the formatting power of Markdown, Markdown Extra, and regular HTML.

For simplicity, you’ll want to stick with Markdown/Markdown Extra wherever you can, but on occasion you may want more control. You can use regular HTML code within your document, but be aware that within HTML tags, Pico will not process Markdown.

Various Variables

When writing your content, there are also some variables you can use to make your life easier. By inserting these into your markdown, you can use their values dynamically in your pages.

• %site_title% - The title of your Pico site.
• %base_url% - The URL of your Pico site. Internal links can be specified using written as %base_url%/sub/page (%base_url%?sub/page without URL rewriting).
• %theme_url% - The URL to the folder of your current theme.
• %meta.*% - By using the meta variable, you can access any YAML variable of the current page, for example, %meta.author% would be replaced with Joe Bloggs in our YAML example above.

Let’s Get Started

Now that we know the basics of creating pages in Pico, we can start generating our own content. Remember, every page starts with a YAML header before the markdown starts. If you’re ever unsure of how this should look, you can check out some of the files in content-sample.

Somewhere to Land

The first page you’ll want to create is your “index” or “landing page”. This is the file that will be loaded when a user visits the base_url of your Pico site. Start by creating a blank file named index.md in the content folder. In the previous section, we discussed how to use YAML and Markdown to create your content. Use what you’ve learned to create a landing page worth visiting!

404 Heading Not Found

If Pico cannot find a given file, it’ll show the content of its internal 404 warning page. This content is loaded in your theme just like any other page, so it makes for a very plesent looking error message. Well, as plesent as an error can be anyway.

However, if you’d like, you can also create your own customized 404 page. Just create a file at content/404.md and Pico will use that instead of its own.

You can also add 404.md to any subfolder and it’ll become the 404 page for that folder. For example, if you wanted to have a special 404 error page for your blog, you might create this file at content/blog/404.md.

Images, Downloads, and Other Assets

So, you’re typing away, creating some content, when you think, “I’d like to put an image here”. You link to an image within your content folder, only to discover that it the image generates a 404 error.

If you’re using our recommended [Apache][ApacheConfig] or [Nginx][NginxConfig], this happened because we deny access to the content folder by default for security reasons. You probably don’t want somebody else probing around in your site’s content folder either.

Instead, all images, downloads, and other website assets should be placed in the assets folder. You’ll find this location in the root of your Pico install. How you choose to organize this folder is entirely up to you.

It may seem counter-intuitive at first, but ultimately, we feel it’s tidier this way. It stops your content folder from being overrun with files that don’t belong there.

It’s easy to link to an item in your assets folder, just use %assets_url% in your Markdown. For example ![Image Title](%assets_url%/image.png).

To Blog or Not to Blog

Pico is not blogging software. That being said, It is fairly easy to create a blog using Pico, as long as you’re aware of it’s limitations. Pico lacks many standard blogging features, such as authentication, tagging, pagination, and social features. There are third party plugins available to help bridge this gap though.

Also, Twig itself is a pretty powerful templating language. If you’re determined, you can actually implement many of these features right at the theme level!

In the not-too-distant future, Pico 2.0 will ship with optional, but officially supported blogging plugins and tools. We’ve even got an official editor in the works, so stay tuned.

In the meantime, see what you can do with the current version. You’ll find that Pico is incredibly extendable.

Check out our Cookbook for some tips and code snippets that will help you use Pico for blogging.

Up Next…

You’ve installed Pico and now you’ve created a simple page or two. What now? Well, Pico’s default theme is a little sparse. It’s not really meant to be used in production, but rather as a learning resource. The default theme provides a great example of how to implement Pico’s most basic features.

But if all you’ve used is the Default Theme, you’ve only scratched the surface of what Pico is really capable of. The real power of Pico is in customizing it to meet your own needs!

How do you do this though? That’s what our next guide will cover. You’ll learn how to customize Pico using the powerful template engine, Twig. Click through to proceed to the next article. We’ll see you there!

Theming with Twig