try pelican
I just forget the usage again and again,so I decided to WcRoIpTyE it=.=
getting start
installing
Pelican currently runs best on Python 2.7.x and 3.3+; earlier versions of Python are not supported.
You can install Pelican via several different methods. The simplest is via pip:
pip install pelican
If you plan on using Markdown as a markup format, you’ll need to install the Markdown library:
pip install markdown
Typographical enhancements can be enabled in your settings file, but first the requisite Typogrify library must be installed:
pip install typogrify
upgrading
pip install --upgrade pelican
kickstart your site
pelican-quickstart
yourproject/
├── content
│ └── (pages)
├── output
├── develop_server.sh
├── fabfile.py
├── Makefile
├── pelicanconf.py # Main settings file
└── publishconf.py # Settings to use when ready to publish
writing content
articles and pages
Pelican considers “articles” to be chronological content, such as posts on a blog, and thus associated with a date.
The idea behind “pages” is that they are usually not temporal in nature and are used for content that does not change very often.
file metadata
Pelican tries to be smart enough to get the information it needs from the file system (for instance, about the category of your articles), but some information you need to provide in the form of metadata inside your files.
Metadata syntax for Markdown posts should follow this pattern:
Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds
This is the content of my super blog post.
pages
If you create a folder named pages inside the content folder, all the files in it will be used to generate static pages, such as About or Contact pages. (See example filesystem layout below.)
You can use the DISPLAY_PAGES_ON_MENU setting to control whether all those pages are displayed in the primary navigation menu. (Default is True.)
If you want to exclude any pages from being linked to or listed in the menu then add a status: hidden attribute to its metadata. This is useful for things like making error pages that fit the generated theme of your site.
linking to internal content
it's useful i think
From Pelican 3.1 onwards, it is now possible to specify intra-site links to files in the source content hierarchy instead of files in the generated hierarchy. This makes it easier to link from the current post to other content that may be sitting alongside that post (instead of having to determine where the other content will be placed after site generation).
To link to internal content (files in the content directory), use the following syntax for the link target: {filename}path/to/file Note: forward slashes, /, are the required path separator in the {filename} directive on all operating systems, including Windows.
linking to static files
Linking to non-article or non-page content uses the same {filename} syntax as described above. It is important to remember that those files will not be copied to the output directory unless the source directories containing them are included in the STATIC_PATHS setting of the project’s pelicanconf.py file. Pelican’s default configuration includes the images directory for this, but others must be added manually. Forgetting to do so will result in broken links.
mixed content in the same directory
Starting with Pelican 3.5, static files can safely share a source directory with page source files, without exposing the page sources in the generated site. Any such directory must be added to both STATIC_PATHS and PAGE_PATHS (or STATIC_PATHS and ARTICLE_PATHS). Pelican will identify and process the page source files normally, and copy the remaining files as if they lived in a separate directory reserved for static files.
Note: Placing static and content source files together in the same source directory does not guarantee that they will end up in the same place in the generated site. The easiest way to do this is by using the {attach} link syntax (described below). Alternatively, the STATIC_SAVE_AS, PAGE_SAVE_AS, and ARTICLE_SAVE_AS settings (and the corresponding *_URL settings) can be configured to place files of different types together, just as they could in earlier versions of Pelican.
attaching static files
Starting with Pelican 3.5, static files can be “attached” to a page or article using this syntax for the link target: {attach}path/to/file This works like the {filename} syntax, but also relocates the static file into the linking document’s output directory. If the static file originates from a subdirectory beneath the linking document’s source, that relationship will be preserved on output. Otherwise, it will become a sibling of the linking document.
This only works for linking to static files, and only when they originate from a directory included in the STATIC_PATHS setting.
linking to authors,categories,index and tags
You can link to authors, categories, index and tags using the {author}name, {category}foobar, {index} and {tag}tagname syntax.
deprecated internal link syntax
To remain compatible with earlier versions, Pelican still supports vertical bars (||) in addition to curly braces ({}) for internal links. For example: |filename|an_article.rst, |tag|tagname, |category|foobar. The syntax was changed from || to {} to avoid collision with Markdown extensions or reST directives. Support for the old syntax may eventually be removed.
importing an existing site
It is possible to import your site from WordPress, Tumblr, Dotclear, and RSS feeds using a simple script. See Importing an existing site.
translations
syntax highlighting
publishing drafts
publish your site
site generation
Once Pelican is installed and you have some content (e.g., in Markdown or reST format), you can convert your content into HTML via the pelican command, specifying the path to your content and (optionally) the path to your settings file:
pelican /path/to/your/content/ [-s path/to/your/settings.py]
The above command will generate your site and save it in the output/ folder, using the default theme to produce a simple site. The default theme consists of very simple HTML without styling and is provided so folks may use it as a basis for creating their own themes.
When working on a single article or page, it is possible to generate only the file that corresponds to that content. To do this, use the --write-selected argument, like so:
pelican --write-selected output/posts/my-post-title.html
Note that you must specify the path to the generated output file — not the source content. To determine the output file name and location, use the --debug flag. If desired, --write-selected can take a comma-separated list of paths or can be configured as a setting. (See: Writing only selected content)
Pelican has other command-line switches available. Have a look at the help to see all the options you can use:
pelican --help
viewing the generated files
The files generated by Pelican are static files, so you don’t actually need anything special to view them. You can use your browser to open the generated HTML files directly:
firefox output/index.html
Because the above method may have trouble locating your CSS and other linked assets, running a simple web server using Python will often provide a more reliable previewing experience.
For Python 2, run:
cd output
python -m SimpleHTTPServer
For Python 3,run:
cd output
python -m http.server
Once the basic server has been started, you can preview your site at http://localhost:8000/
deployment
After you have generated your site, previewed it in your local development environment, and are ready to deploy it to production, you might first re-generate your site with any production-specific settings (e.g., analytics feeds, etc.) that you may have defined:
pelican content -s publishconf.py
To base your publish configuration on top of your pelicanconf.py, you can import your pelicanconf settings by including the following line in your publishconf.py:
from pelicanconf import *
If you have generated a publishconf.py using pelican-quickstart, this line is included by default.
The steps for deploying your site will depend on where it will be hosted. If you have SSH access to a server running Nginx or Apache, you might use the rsync tool to transmit your site files:
rsync -avc --delete output/ host.example.com:/var/www/your-site/
There are many other deployment options, some of which can be configured when first setting up your site via the pelican-quickstart command. See the Tips page for detail on publishing via GitHub Pages.
automation
While the pelican command is the canonical way to generate your site, automation tools can be used to streamline the generation and publication flow. One of the questions asked during the pelican-quickstart process pertains to whether you want to automate site generation and publication. If you answered “yes” to that question, a tasks.py and Makefile will be generated in the root of your project. These files, pre-populated with certain information gleaned from other answers provided during the pelican-quickstart process, are meant as a starting point and should be customized to fit your particular needs and usage patterns. If you find one or both of these automation tools to be of limited utility, these files can deleted at any time and will not affect usage of the canonical pelican command.
Following are automation tools that “wrap” the pelican command and can simplify the process of generating, previewing, and uploading your site.
invoke
The advantage of Invoke is that it is written in Python and thus can be used in a wide range of environments. The downside is that it must be installed separately. Use the following command to install Invoke, prefixing with sudo if your environment requires it:
pip install invoke
Take a moment to open the tasks.py file that was generated in your project root. You will see a number of commands, any one of which can be renamed, removed, and/or customized to your liking. Using the out-of-the-box configuration, you can generate your site via:
invoke build
If you’d prefer to have Pelican automatically regenerate your site every time a change is detected (which is handy when testing locally), use the following command instead:
invoke regenerate
To serve the generated site so it can be previewed in your browser at http://localhost:8000/:
invoke serve
If during the pelican-quickstart process you answered “yes” when asked whether you want to upload your site via SSH, you can use the following command to publish your site via rsync over SSH:
invoke publish
These are just a few of the commands available by default, so feel free to explore tasks.py and see what other commands are available. More importantly, don’t hesitate to customize tasks.py to suit your specific needs and preferences.
make
A Makefile is also automatically created for you when you say “yes” to the relevant question during the pelican-quickstart process. The advantage of this method is that the make command is built into most POSIX systems and thus doesn’t require installing anything else in order to use it. The downside is that non-POSIX systems (e.g., Windows) do not include make, and installing it on those systems can be a non-trivial task.
If you want to use make to generate your site using the settings in pelicanconf.py, run:
make html
To generate the site for production, using the settings in publishconf.py, run:
make publish
If you’d prefer to have Pelican automatically regenerate your site every time a change is detected (which is handy when testing locally), use the following command instead:
make regenerate
To serve the generated site so it can be previewed in your browser at http://localhost:8000/:
make serve
Normally you would need to run make regenerate and make serve in two separate terminal sessions, but you can run both at once via:
make devserver
The above command will simultaneously run Pelican in regeneration mode as well as serve the output at http://localhost:8000.
When you’re ready to publish your site, you can upload it via the method(s) you chose during the pelican-quickstart questionnaire. For this example, we’ll use rsync over ssh:
make rsync_upload
(The default Makefile and devserver.sh scripts use the python and pelican executables to complete its tasks. If you want to use different executables, such as python3, you can set the PY and PELICAN environment variables, respectively, to override the default executable names.)