Home

authoring editing

Overview

Adding posts to your PyKwiki consists of two main pieces.

  1. Some way to get your content to a server.
  2. Some way to run pykwiki cache to cache your content.

Things to know

Technical knowledge:

  1. A basic understanding of Markdown.
  2. A basic understanding of the YAML data format.

PyKwiki knowledge:

  1. New posts must be somewhere in the source directory.
  2. New posts must have the .md extension unless a different extension has been specified in config.yaml (the source_ext property).
  3. Post content must be in the Markdown format.
  4. For best cross-platform perfomance, post names should not have any spaces.
  5. Post file names should not conflict with the "special" theme files: search or posts.

Remote editing

If you don't have access to the server, or if you prefer to use your own text editor to edit files, then you can sync files between your computer and the server.

The server needs some way to cache your files. One way to do this is to have your server administrator setup a cron job.

See: Remote Editing Tutorial

Creating posts

A simple example

1. Open the new post

$ cd /path/to/myproject/source
$ nano my-new-post.md

2. Add content to the post

Put the following in as your page content, and save the post

[[
title: My New Post
]]

# Here is a new post!

* It's easy
* It's fun
* It's fast

The double brackets [[ and ]] indicate the post data block. Here you can specify various information about your pages. Learn more about the post data block.

Note: Post properties in this block must be either valid YAML or valid JSON.

3. (optionally) Add a link for a menu entry

PyKwiki parses the links.yaml file to generate the site menu. Once you understand the format of links.yaml, adding links is very quick and easy.

4. Cache the post

$ cd /path/to/myproject
$ pykwiki cache

Post data block

The post data block is entirely optional, but it adds a lot of functionality to PyKwiki. The minimal recommended fields are title and tags.

This block should appear at the top of a post, and must be enclosed in [[ and ]]. 

# The post title will show in search results, as well as 
#   in the title bar of the browser.
title: My Post Title
# The post author is displayed by most themes.
#   Can be a comma separated list of multiple authors.
author: Harry Potter
# Post tags are essentially categories. 
tags: [A, YAML, List, Of, Tags]
# A page description is mostly useful for search engines
#   but it will be used as the page blurb if none is found
description: A simple description of my page,
    this information is usually used by themes to make 
    your site more search engine friendly. If no blurb
    is specified, this will be used as the page blurb.
# The page blurb can be set to "auto", which allows
#   PyKwiki to generate one based on the first 50 words
#   in the body of a page.
blurb: This is my post blurb. It will be used as the short 
    description in search results. If I want this to be 
    autogenerated, I should set its value to "auto"
    for example: blurb: auto
# Post keywords are used by SEO
keywords: This is, a string, of comma separated words
# The timestamp of the page. It MUST match the 
#   `timestamp_format` specified in config.yaml
timestamp: 2013-11-01 21:45
# Pages that are flagged as private are basically unpublished.
#   They are not searchable and can only be reached by a direct link.
private: false
# The nowrap option is used by some themes to prevent wrapping
#   the post content in a "container"
nowrap: false