소스 검색

moving docs location to docs/

master
Charles Reid 3 년 전
부모
커밋
9c04483993
  1. 1
      .gitignore
  2. 108
      Adding.md
  3. 14
      Before.md
  4. 72
      Configuring.md
  5. 36
      Generating.md
  6. 135
      Getting.md
  7. 168
      Hosting.md
  8. 26
      README.md
  9. 27
      Serving.md
  10. 58
      Theming.md
  11. 28
      mkdocs.yml

1
.gitignore

@ -0,0 +1 @@
site/

108
Adding.md

@ -1,108 +0,0 @@
# Adding content to your site
Now that you have generated your site with the
`pelican` command, and have used Python to serve
your documentation with a simple HTTP server,
you have all the tools you need to start creating
content for your website.
Also see [writing content](http://docs.getpelican.com/en/stable/content.html)
page of pelican documentation.
Pelican has two types of content: pages (unchanging, no chronology)
and articles (blog posts). We will cover each below.
## Adding blog posts to your site
Let's cover how you add new content to your site.
By default, Pelican is set up to create blog sites,
so we'll cover how to create a blog. Creating static
sites requires custom themes, and we won't get into that
in this document.
In the `content/` directory (or `content/posts/` directory),
you create blog posts by adding Markdown files, and specify
metadata using a YAML header.
Here's a Markdown template for a blog post:
```
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.
```
Note that not everything is necessary (e.g., Slug, Authors, Summary).
Ultimately the variables in the YAML headers of each
blog post are passed to the theme's page templates,
so what information gets used depends on the theme
that you use.
## Adding pages to your site
Metadata for
## Linking to other pages
As shown in the [linking to internal content](http://docs.getpelican.com/en/stable/content.html#linking-to-internal-content)
section of the pelican docs, you can link to other files
**`article1.md`:**
```plain
Title: The first article
Date: 2012-12-01 10:02
See below intra-site link examples in Markdown format.
[a link to another file]({filename}/article2.md)
```
**`article2.md`:**
```plain
Title: The second article
Date: 2012-12-01 10:02
More markdown goes _here_.
[link back to article one]({filename}/article1.md)
```
See [docs](http://docs.getpelican.com/en/stable/content.html#linking-to-internal-content) for details.
## Linking to static files
For example, a project’s content directory might be structured like this:
Suppose you have a directory structure like this:
```
content
├── images
│ └── han.jpg
├── pdfs
│ └── menu.pdf
└── pages
└── test.md
```
then in `test.md` you would link to other files like this:
```
![Alt Text]({filename}/images/han.jpg)
[Our Menu]({filename}/pdfs/menu.pdf)
```
See [docs](http://docs.getpelican.com/en/stable/content.html#linking-to-internal-content)
for details...

14
Before.md

@ -1,14 +0,0 @@
## Before You Start
You'll need to have [Pelican](https://github.com/getpelican/pelican) installed.
If you want to use Markdown with Pelican,
you'll also need to install Markdown.
```text
$ pip install Markdown
$ pip install pelican
```
Also see [installation page](http://docs.getpelican.com/en/stable/install.html)
of Pelican documentation.

72
Configuring.md

@ -1,72 +0,0 @@
## Configuring Your Pelican Site
The `pelicanconf.py` file contains all configuration variables
that [Pelican](https://github.com/getpelican/pelican) sites need to set.
Some of the configuration variables are common to all Pelican sites,
others are particular to the theme you are using.
Here's an example configuration file from
[magic-flying-pelican](https://github.com/charlesreid1/magic-flying-pelican):
**`pelicanconf.py`:**
```python
import markdown
AUTHOR = u'charlesreid1'
SITENAME = u'ginsberg bot flock'
SITEURL = ''
PATH = 'content'
TIMEZONE = 'America/Los_Angeles'
DEFAULT_LANG = u'en'
# --------------8<---------------------
# Theme
THEME = 'simple-bootstrap'
# https://github.com/getpelican/pelican-themes/tree/master/simple-bootstrap
# --------------8<---------------------
# Files and content
# This will look for a directory img/
# inside the directory content/
# The contents of img/ will be available at
# {{ SITEURL }}/img
STATIC_PATHS = ['img']
# If we want to create static pages,
# we should put them in content/pages
PAGE_PATHS = ['pages']
# If we want to create blog posts (articles),
# we should put them in content/posts
ARTICLE_PATHS = ['posts']
# --------------8<---------------------
# idk just some dumb stuff
DISPLAY_PAGES_ON_MENU = False
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None
DEFAULT_PAGINATION = False
```
This will configure the `content/` directory
to contain a `posts/` folder with blog posts
and a `pages/` folder with static pages.
There's a lot more that can be done with the
configuration file, but much of it requires
custom themes, so we'll leave it at that.
See the [settings page](http://docs.getpelican.com/en/stable/settings.html?highlight=configuration)
of the pelican documentation for details.

36
Generating.md

@ -1,36 +0,0 @@
# Generating your static site
To generate your static site with [Pelican](https://github.com/getpelican/pelican),
use the `pelican content` command, run from
the `pelican/` directory (see [getting started](Getting.md)
for a guide to the pelican directory layout):
```plain
$ pelican
```
This will generate the static site content into
the `output/` folder.
Inputs: `content/`
Output: `output/`
To modify the input folder, change the `PATH` variable
in `pelicanconf.py`:
```plain
PATH = 'my_custom_content_dir'
```
To modify the output directory, set the
`OUTPUT_PATH` variable in `pelicanconf.py`:
```plain
OUTPUT_PATH = 'my_custom_output_dir'
```
See the [settings page](http://docs.getpelican.com/en/stable/settings.html)
of the pelican documentation for more variables
that can be set in the `pelicanconf.py` file.

135
Getting.md

@ -1,135 +0,0 @@
# Getting Started with Pelican
There are a few things you'll need to get started with [Pelican](https://github.com/getpelican/pelican):
* (required) `pelicanconf.py` - pelican configuration file
* (required) `content/` - directory containing materials to render into a static site
* (optional) theme - either a local directory containing a theme, or a system-wide pelican theme
Use the [magic-flying-pelican](https://github.com/charlesreid1/magic-flying-pelican)
repository as a seed repo for getting started with Pelican.
Basically, copy the contents of the `pelican/` directory
in [magic-flying-pelican](https://github.com/charlesreid1/magic-flying-pelican)
into your own repository, and modify the contents for
your own static site.
We'll walk through what the `pelican/` directory contains and what you
need to change to get a simple static site up and running.
## How Pelican Works
Let's cover the 101 of how Pelican works.
Pelican takes a pile of HTML, markdown, and other files,
and compiles them into a static site. (The advantage of
using a static site instead of a dynamic server like
Flask or a dynamic language like PHP is speed.)
To do that, it reads configuration settings from
`pelicanconf.py`, which tell Pelican where to look
for the raw files, as well as other settings like
the theme to use.
The default location of content is the `content/`
directory, but more can be added.
The default behavior for Pelican is to serve a blog
with a few static pages, but users can define themes
that are static pages only (no blog component).
The themes work by providing a set of static files
and a set of HTML Jinja templates. Pelican uses
the static content and the theme to render the
final page.
See [pelican-themes](https://github.com/getpelican/pelican-themes)
repository for themes.
See [live gallery](http://www.pelicanthemes.com/)
of pelican themes.
## Repository and Branch Layout
When using Pelican to create a static site on Github Pages,
you will need to organize your repository and set up
branches as follows.
### Recommended way: project page
If you are hosting a project Github Pages site
(that is, a Github Pages page for any arbitrary
Github project), you should organize your repo
as follows:
* `gh-pages` branch contains all static content
* `master` branch contains the pelican site
### Uncommon way: personal page
If you are hosting a personal Github Pages site
(a repository under the account `@yourusername`
called `yourusername.github.io`), this should be
organized as follows:
* `master` branch contains all static content
* `source` branch contains the `pelican/` directory
### Clean way: pelican as a separate branch
If you have a large project or you really don't want
to clutter your repository branch with Pelican files,
you can also set up a three-branch model as follows:
* `master` branch contains the source code for your project (no Pelican files)
* `source` branch contains the Pelican files for your site
* `gh-pages` contains all static content for the Github Pages page
## Directory Layout
While Pelican is flexible enough to handle many
directory layouts, let's cover a common pattern:
putting markdown files into `content/`.
```
my-cool-project/
pelican/
pelicanconf.py
output/
index.html
...
content/
posts/
blog-post-1.md
blog-post-2.md
blog-post-3.md
pages/
faq.md
about.md
contact.md
img/
my-image-1.jpg
my-image-2.jpg
my-image-3.jpg
```
The pelican directory contains a configuration
file `pelicanconf.py`, a folder with content
`content/`, and an output directory `output/`
where the final static files for the site go.
(See [configuring](Configuring.md)).
The `output/` directory will not be present
until you generate site content (see [generating](Generating.md)).
The `output/` directory should be ignored by git.
In a later section of this document we will cover
a pattern for linking output to a Github Pages
site (see [workflow: update](WorkflowUpdate.md)).

168
Hosting.md

@ -1,168 +0,0 @@
# Hosting on Github Pages
Now that you've configured your [Pelican](https://github.com/getpelican/pelican) site,
created your content, viewed it, modified it,
and are happy with it, you're ready to deploy
your site somewhere viewable by the public.
Enter Github Pages.
Github provides free web hosting for static content
for _every single repository on Github_.
That means you can deploy your static site
to Github Pages for no-hassle serverless
web hosting.
(Also see the [publish](http://docs.getpelican.com/en/stable/publish.html)
page of the pelican documentation.)
## Differences between personal and project pages
In this walkthrough we assume the most common scenario
of deploying a page on Github Pages for a project.
Setting up a personal page requires changing
branch names - see [getting started](Getting.md)
and the section on branches in particular.
Change `gh-pages` to `master` and `master` to `source`.
The rest of the document will assume you are creating
a project page.
## Where is it?
Where do Github Pages live?
If your username is `username` and your project name is `projectname`,
the Github source code is at:
```
https://github.com/username/projectname
```
and the Github Pages page will be at:
```
https://username.github.io/projectname
```
## Initializing gh-pages branch
Before you begin, you have to create a `gh-pages` branch.
We want to create a new branch that is _completely independent_
of all other branches, because this branch will only contain
the static content of our website - no code, no readmes,
nothing but HTML, CSS, and Javascript.
We want to link the `gh-pages` branch, which will contain
the site's static content, with the `output/` directory,
where Pelican generates all of its static content.
Remove the output directory, and clone a copy of
your repo to the output directory:
```
$ cd pelican/
$ rm -rf output/
$ git clone https://github.com/username/projectname.git output
$ cd output/
```
Now create a new orphan branch - that's the git terminology
for a branch that shares no history with any other branches.
Call it `gh-pages`:
```
$ git checkout --orphan gh-pages
```
Now all the content that was in the master branch
will show up as untracked files, because the new
`gh-pages` branch is totally empty.
Remove everything in the directory except
the `.git` directory:
```
$ rm -rf *
$ rm -rf .gitignore .gitmodules
```
Now add a simple "Hello world" page that we'll use
to make sure our Github Pages page is being
hosted correctly:
```
$ echo '<h2>Hello world!</h2>' > index.html
$ git add index.html
$ git commit index.html -m 'Initial commit of gh-pages branch'
$ git push origin gh-pages
```
Now we have our intiial commit on the
`gh-pages` branch.
## Enabling Github Pages
We have one additional step to cover.
After we create the `gh-pages` branch,
we want to tell Github Pages that we have
web content on that branch that we want
Github to host.
Go to the repository settings,
and scroll down to the Github Pages
setting. Select the drop-down option
to host your Github Pages content
from the `gh-pages` branch.
Now visit the URL to check out your
Hello World page:
```
https://username.github.io/projectname
```
## Adding the real content
We have a hello world page working,
now let's add the real Pelican content.
Back in the `pelican/` directory,
clean out the `output/` directory
(we'll be making everything from
scratch):
```
$ rm -rf output/*
```
Don't remove the `output/` directory itself though!
Now make the content:
```
$ pelican content
```
Now add the content to the `gh-pages` branch
and push it to Github to deploy it:
```
$ cd output/
$ git add -A .
$ git commit -a -m 'Updating site'
$ git push origin gh-pages
```
This will push the new static site (this time with
the Pelican output) to the `gh-pages` branch on Github.
Sometimes the site updates really fast (few seconds),
sometimes it takes longer, but never more than about a minute.
Don't forget to add a link to your new page
in the repository description (and in your README)
to make it easier to find!

26
README.md

@ -1,25 +1,9 @@
# How Do I Pelican?
# how do I pelican?
This is a simple explanation of how to get started
using Pelican to build a static site.
It will skip a lot of the details in the
interest of simplicity.
See [how do I pelican?](https://pages.charlesreid1.com/how-do-i-pelican)
(the website).
The outline:
Source repository on git.charlesreid1.com [here](https://git.charlesreid1.com/charlesreid1/how-do-i-pelican).
* [Before you start - installing Pelican](Before.md)
* [Getting started with Pelican](Getting.md)
* [Configuring your Pelican site](Configuring.md)
* [Theming your Pelican site](Theming.md)
* [Generating your static site](Generating.md)
* [Serving your static site](Serving.md)
* [Adding content](Adding.md)
* [Hosting on Github Pages](Hosting.md)
Also check out the workflows pages for
copy-and-paste commands for working with
your pelican site:
* [Workflow: Initialization of the Github Pages site](WorkflowInit.md)
* [Workflow: Update the Github Pages site](WorkflowUpdate.md)
Source repository on github [here](#).

27
Serving.md

@ -1,27 +0,0 @@
# Serving your static site
Once you've run the `pelican` command to generate
your static site, you'll want to see what it looks like.
To do this, you need to run a simple HTTP server -
nothing fancy.
(Now you can see the advantage of a static site.)
Run a simple HTTP server with python, which has a
built-in HTTP server that can be run from the
command line.
Run the server from the `output/` directory,
which contains the static content for your site.
```
$ cd pelican/output/
$ python -m http.server # serve content on localhost:8000
$ python -m http.server 8888 # serve content on localhost:8888
```
Now navigate to `localhost:8000` or `localhost:8888`
in your browser to view your static site.

58
Theming.md

@ -1,58 +0,0 @@
# Theming your Pelican site
Custom themes are where Pelican becomes really powerful.
For this tutorial, though, we'll stick to the basics.
See [pelican-themes](https://github.com/getpelican/pelican-themes)
on Github for a full list of themes.
See [pelicanthemes.com](http://pelicanthemes.com/)
for a gallery of themes.
## gum theme
For this example, we'll use [gum](https://github.com/getpelican/pelican-themes/tree/master/gum),
a simple Bootstrap theme.
The theme's README (linked to above) tells us what settings to include
in our `pelicanconf.py`.
In this case, we'll leave most of these blank so they don't show up
in the final page:
```
GITHUB_URL = ''
TWITTER_URL = ''
FACEBOOK_URL = ''
GOOGLEPLUS_URL = ''
GOOGLE_ANALYTICS_ID = ''
GOOGLE_ANALYTICS_SITENAME = ''
```
To use the gum theme, we have to install it.
Start by checking out the pelican-themes repo:
```
$ git clone --recursive https://github.com/getpelican/pelican-themes
$ cd pelican-themes
$ pelican-themes -i gum
```
If you modify or update the theme, you can
use the `-U` flag (for Update) with `pelican-themes`:
```
$ pelican-themes -U gum
```
Now you can set the gum theme in your `pelicanconf.py`
by setting the `THEME` variable:
```
THEME="gum"
```

28
mkdocs.yml

@ -0,0 +1,28 @@
site_name: how do I pelican?
docs_dir: docs
site_dir: site
extra_css:
- css/custom.css
theme:
name: null
custom_dir: 'mkdocs-material/material'
palette:
primary: 'indigo'
accent: 'indigo'
logo:
icon: 'help'
font:
text: 'Source Serif Pro'
code: 'PT Mono'
markdown_extensions:
- admonition
pages:
- "Index" : "index.md"
- "Before You Start" : "Before.md"
- "Getting Started with Pelican" : "Getting.md"
- "Configuring Your Pelican Site" : "Configuring.md"
- "Theming Your Pelican Site" : "Theming.md"
- "Generating Your Pelican Site" : "Generating.md"
- "Serving Your Static Site" : "Serving.md"
- "Adding Content" : "Adding.md"
- "Hosting on Github Pages" : "Hosting.md"
불러오는 중...
취소
저장