diff --git a/docs/getting_started.rst b/docs/getting_started.rst
index aa04dd03..954dac3d 100644
--- a/docs/getting_started.rst
+++ b/docs/getting_started.rst
@@ -1,15 +1,70 @@
Getting started
###############
-Installing
-==========
+Kickstart a blog
+================
-You're ready? Let's go! You can install Pelican via several different methods.
+You're ready? Let's go! Following is a brief tutorial for those who want to get
+started right away. Subsequent sections below will cover individual topics in
+greater detail. To get started, here are some recommended install steps for
+Pelican::
+
+ $ sudo pip install --upgrade virtualenv virtualenvwrapper
+ $ mkvirtualenv pelican
+ $ pip install pelican Markdown
+ $ mkdir ~/code/yoursitename # (where you want your new site code to be saved)
+ $ cd ~/code/yoursitename
+ $ setvirtualenvproject
+ $ pelican-quickstart
+
+Once you've run that last ``pelican-quickstart`` command, you'll be asked some
+questions about your site. Once you finish answering all the questions, you can
+begin adding content to the *content* folder that has been created for you.
+(See *Writing articles using Pelican* section below for more information
+about how to format your content.) Once you have some content to generate, you
+can convert it to HTML via the following command::
+
+ $ make html
+
+If you'd prefer to have Pelican automatically regenerate your site every time a
+change is detected (handy when testing locally), use the following command
+instead::
+
+ $ make regenerate
+
+To preview the site in your browser, open a new terminal tab and enter::
+
+ $ workon yoursitename
+ $ make serve
+
+Visit http://localhost:8000 in your browser to see your site.
+
+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
+
+That's it! Your site should now be live.
+
+Closing the current terminal session will also close the virtual environment in
+which we installed Pelican. In the future, when you want to work on your site,
+you can activate its virtual environment via::
+
+ $ workon yoursitename
+
+Not only will that command activate your new site's virtual environment, but it
+will also automatically change your working directory to your site project.
+
+Installing Pelican
+==================
+
+You can install Pelican via several different methods.
The simplest is via `pip `_::
$ pip install pelican
-If you don't have pip installed, an alternative method is easy_install::
+If you don't have ``pip`` installed, an alternative method is ``easy_install``::
$ easy_install pelican
@@ -18,12 +73,12 @@ a virtual environment for Pelican via `virtualenv `_
and `virtualenvwrapper `_
before installing Pelican::
- $ pip install virtualenvwrapper
+ $ sudo pip install --upgrade virtualenv virtualenvwrapper
$ mkvirtualenv pelican
Once the virtual environment has been created and activated, Pelican can be
-be installed via pip or easy_install as noted above. Alternatively, if you
-have the project source, you can install Pelican using the distutils
+be installed via ``pip`` or ``easy_install`` as noted above. Alternatively, if
+you have the project source, you can install Pelican using the distutils
method::
$ cd path-to-Pelican-source
@@ -34,6 +89,11 @@ version of Pelican rather than a stable release, use the following command::
$ pip install -e git://github.com/ametaireau/pelican#egg=pelican
+If you plan on using Markdown as a markup format, you'll need to install the
+Markdown library as well::
+
+ $ pip install Markdown
+
Upgrading
---------
@@ -83,7 +143,6 @@ following syntax (give your file the ``.rst`` extension)::
:category: yeah
:author: Alexis Metaireau
-
You can also use Markdown syntax (with a file ending in ``.md``).
Markdown generation will not work until you explicitly install the ``Markdown``
package, which can be done via ``pip install Markdown``. Metadata syntax for
@@ -105,27 +164,28 @@ example, a file located at ``python/foobar/myfoobar.rst`` will have a category o
Generate your blog
------------------
-To launch Pelican, just use the ``pelican`` command::
+The ``make`` shortcut commands mentioned in the ``Kickstart a blog`` section
+are mostly wrappers around the ``pelican`` command that generates the HTML from
+the content. The ``pelican`` command can also be run directly::
$ pelican /path/to/your/content/ [-s path/to/your/settings.py]
-And… that's all! Your weblog will be generated and saved in the ``content/``
-folder.
+The above command will generate your weblog and save it in the ``content/``
+folder, using the default theme to produce a simple site. It's not
+very sexy, as it's just simple HTML output (without any style). You can create
+your own style if you want.
-The above command will use the default theme to produce a simple site. It's not
-very sexy, as it's just simple HTML output (without any style).
-
-You can create your own style if you want. Have a look at the help to see all
-the options you can use::
+Pelican has other command-line switches available. Have a look at the help to
+see all the options you can use::
$ pelican --help
-Kickstart a blog
-----------------
+Auto-reload
+-----------
-You also can use the ``pelican-quickstart`` script to start a new blog in
-seconds by just answering a few questions. Just run ``pelican-quickstart`` and
-you're done! (Added in Pelican 3.0)
+It's possible to tell Pelican to watch for your modifications, instead of
+manually re-running it every time you want to see your changes. To enable this,
+run the ``pelican`` command with the ``-r`` or ``--autoreload`` option.
Pages
-----
@@ -209,13 +269,6 @@ For Markdown, format your code blocks thusly::
The specified identifier should be one that appears on the
`list of available lexers `_.
-Auto-reload
------------
-
-It's possible to tell Pelican to watch for your modifications, instead of
-manually re-running it every time you want to see your changes. To enable this,
-run the ``pelican`` command with the ``-r`` or ``--autoreload`` option.
-
Publishing drafts
-----------------
diff --git a/docs/settings.rst b/docs/settings.rst
index 78ede790..3c557e87 100644
--- a/docs/settings.rst
+++ b/docs/settings.rst
@@ -59,18 +59,16 @@ Setting name (default value) What doe
`PDF_GENERATOR` (``False``) Set to True if you want to have PDF versions
of your documents. You will need to install
`rst2pdf`.
-`RELATIVE_URLS` (``True``) Defines whether Pelican should use relative URLs or
- not.
+`RELATIVE_URLS` (``True``) Defines whether Pelican should use document-relative URLs or
+ not. If set to ``False``, Pelican will use the SITEURL
+ setting to construct absolute URLs.
`PLUGINS` (``[]``) The list of plugins to load. See :ref:`plugins`.
`SITENAME` (``'A Pelican Blog'``) Your site name
`SITEURL` Base URL of your website. Not defined by default,
- which means the base URL is assumed to be "/" with a
- root-relative URL structure. If `SITEURL` is specified
- explicitly, there should be no trailing slash at the end,
- and URLs will be generated with an absolute URL structure
- (including the domain). If you want to use relative URLs
- instead of root-relative or absolute URLs, you should
- instead use the `RELATIVE_URL` setting.
+ so it is best to specify your SITEURL; if you do not, feeds
+ will not be generated with properly-formed URLs. You should
+ include ``http://`` and your domain, with no trailing
+ slash at the end. Example: ``SITEURL = 'http://mydomain.com'``
`STATIC_PATHS` (``['images']``) The static paths you want to have accessible
on the output path "static". By default,
Pelican will copy the 'images' folder to the
@@ -107,6 +105,15 @@ Setting name (default value) What doe
URL settings
------------
+The first thing to understand is that there are currently two supported methods
+for URL formation: *relative* and *absolute*. Document-relative URLs are useful
+when testing locally, and absolute URLs are reliable and most useful when
+publishing. One method of supporting both is to have one Pelican configuration
+file for local development and another for publishing. To see an example of this
+type of setup, use the ``pelican-quickstart`` script as described at the top of
+the :doc:`Getting Started` page, which will produce two separate
+configuration files for local development and publishing, respectively.
+
You can customize the URLs and locations where files will be saved. The URLs and
SAVE_AS variables use Python's format strings. These variables allow you to place
your articles in a location such as '{slug}/index.html' and link to them as
diff --git a/pelican/tools/pelican_quickstart.py b/pelican/tools/pelican_quickstart.py
index 0e713fe8..f747d048 100755
--- a/pelican/tools/pelican_quickstart.py
+++ b/pelican/tools/pelican_quickstart.py
@@ -24,6 +24,7 @@ CONF = {
'ssh_target_dir': '/var/www',
'dropbox_dir' : '~/Dropbox/Public/',
'default_pagination' : 10,
+ 'siteurl': '',
'lang': 'en'
}
@@ -138,35 +139,44 @@ Please answer the following questions so this script can generate the files need
'''.format(v=__version__))
- CONF['basedir'] = os.path.abspath(ask('Where do you want to create your new web site?', answer=str, default=args.path))
+ project = os.path.join(os.environ['VIRTUAL_ENV'], '.project')
+ if os.path.isfile(project):
+ CONF['basedir'] = open(project, 'r').read().rstrip("\n")
+ print('Using project associated with current virtual environment. Will save to:\n%s\n' % CONF['basedir'])
+ else:
+ CONF['basedir'] = os.path.abspath(ask('Where do you want to create your new web site?', answer=str, default=args.path))
+
CONF['sitename'] = ask('What will be the title of this web site?', answer=str, default=args.title)
CONF['author'] = ask('Who will be the author of this web site?', answer=str, default=args.author)
- CONF['lang'] = ask('What will be the default language of this web site ?', str, args.lang or CONF['lang'], 2)
+ CONF['lang'] = ask('What will be the default language of this web site?', str, args.lang or CONF['lang'], 2)
- CONF['with_pagination'] = ask('Do you want to enable article pagination ?', bool, bool(CONF['default_pagination']))
+ if ask('Do you want to specify a URL prefix? e.g., http://example.com ', answer=bool, default=True):
+ CONF['siteurl'] = ask('What is your URL prefix? (see above example; no trailing slash)', str, CONF['siteurl'])
+
+ CONF['with_pagination'] = ask('Do you want to enable article pagination?', bool, bool(CONF['default_pagination']))
if CONF['with_pagination']:
CONF['default_pagination'] = ask('How many articles per page do you want?', int, CONF['default_pagination'])
else:
CONF['default_pagination'] = False
- mkfile = ask('Do you want to generate a Makefile to easily manage your website ?', bool, True)
+ mkfile = ask('Do you want to generate a Makefile to easily manage your website?', bool, True)
if mkfile:
- if ask('Do you want to upload your website using FTP ?', answer=bool, default=False):
- CONF['ftp_host'] = ask('What is the hostname of your FTP server ?', str, CONF['ftp_host'])
+ if ask('Do you want to upload your website using FTP?', answer=bool, default=False):
+ CONF['ftp_host'] = ask('What is the hostname of your FTP server?', str, CONF['ftp_host'])
CONF['ftp_user'] = ask('What is your username on that server?', str, CONF['ftp_user'])
CONF['ftp_target_dir'] = ask('Where do you want to put your web site on that server?', str, CONF['ftp_target_dir'])
- if ask('Do you want to upload your website using SSH ?', answer=bool, default=False):
- CONF['ssh_host'] = ask('What is the hostname of your SSH server ?', str, CONF['ssh_host'])
+ if ask('Do you want to upload your website using SSH?', answer=bool, default=False):
+ CONF['ssh_host'] = ask('What is the hostname of your SSH server?', str, CONF['ssh_host'])
CONF['ssh_port'] = ask('What is the port of your SSH server?', int, CONF['ssh_port'])
CONF['ssh_user'] = ask('What is your username on that server?', str, CONF['ssh_user'])
CONF['ssh_target_dir'] = ask('Where do you want to put your web site on that server?', str, CONF['ssh_target_dir'])
- if ask('Do you want to upload your website using Dropbox ?', answer=bool, default=False):
- CONF['dropbox_dir'] = ask('Where is your Dropbox directory ?', str, CONF['dropbox_dir'])
+ if ask('Do you want to upload your website using Dropbox?', answer=bool, default=False):
+ CONF['dropbox_dir'] = ask('Where is your Dropbox directory?', str, CONF['dropbox_dir'])
try:
- os.makedirs(os.path.join(CONF['basedir'], 'src'))
+ os.makedirs(os.path.join(CONF['basedir'], 'content'))
except OSError, e:
print('Error: {0}'.format(e))
@@ -176,8 +186,17 @@ Please answer the following questions so this script can generate the files need
print('Error: {0}'.format(e))
try:
- with open(os.path.join(CONF['basedir'], 'pelican.conf.py'), 'w') as fd:
- for line in get_template('pelican.conf.py'):
+ with open(os.path.join(CONF['basedir'], 'pelicanconf.py'), 'w') as fd:
+ for line in get_template('pelicanconf.py'):
+ template = string.Template(line)
+ fd.write(template.safe_substitute(CONF))
+ fd.close()
+ except OSError, e:
+ print('Error: {0}'.format(e))
+
+ try:
+ with open(os.path.join(CONF['basedir'], 'publishconf.py'), 'w') as fd:
+ for line in get_template('publishconf.py'):
template = string.Template(line)
fd.write(template.safe_substitute(CONF))
fd.close()
diff --git a/pelican/tools/templates/Makefile.in b/pelican/tools/templates/Makefile.in
index 392336d7..3a3fe74c 100644
--- a/pelican/tools/templates/Makefile.in
+++ b/pelican/tools/templates/Makefile.in
@@ -2,9 +2,10 @@ PELICAN=$pelican
PELICANOPTS=$pelicanopts
BASEDIR=$$(PWD)
-INPUTDIR=$$(BASEDIR)/src
+INPUTDIR=$$(BASEDIR)/content
OUTPUTDIR=$$(BASEDIR)/output
-CONFFILE=$$(BASEDIR)/pelican.conf.py
+CONFFILE=$$(BASEDIR)/pelicanconf.py
+PUBLISHCONF=$$(BASEDIR)/publishconf.py
FTP_HOST=$ftp_host
FTP_USER=$ftp_user
@@ -23,10 +24,11 @@ help:
@echo 'Usage: '
@echo ' make html (re)generate the web site '
@echo ' make clean remove the generated files '
- @echo ' ftp_upload upload the web site using FTP '
- @echo ' ssh_upload upload the web site using SSH '
- @echo ' dropbox_upload upload the web site using Dropbox '
- @echo ' rsync_upload upload the web site using rsync/ssh'
+ @echo ' make publish generate using production settings '
+ @echo ' ftp_upload upload the web site via FTP '
+ @echo ' ssh_upload upload the web site via SSH '
+ @echo ' dropbox_upload upload the web site via Dropbox '
+ @echo ' rsync_upload upload the web site via rsync/ssh '
@echo ' '
@@ -37,23 +39,31 @@ $$(OUTPUTDIR)/%.html:
$$(PELICAN) $$(INPUTDIR) -o $$(OUTPUTDIR) -s $$(CONFFILE) $$(PELICANOPTS)
clean:
- rm -fr $$(OUTPUTDIR)
- mkdir $$(OUTPUTDIR)
+ find $$(OUTPUTDIR) -mindepth 1 -delete
-dropbox_upload: $$(OUTPUTDIR)/index.html
+regenerate: clean
+ $$(PELICAN) -r $$(INPUTDIR) -o $$(OUTPUTDIR) -s $$(CONFFILE) $$(PELICANOPTS)
+
+serve:
+ cd $$(OUTPUTDIR) && python -m SimpleHTTPServer
+
+publish:
+ $$(PELICAN) $$(INPUTDIR) -o $$(OUTPUTDIR) -s $$(PUBLISHCONF) $$(PELICANOPTS)
+
+dropbox_upload: publish
cp -r $$(OUTPUTDIR)/* $$(DROPBOX_DIR)
-ssh_upload: $$(OUTPUTDIR)/index.html
+ssh_upload: publish
scp -P $$(SSH_PORT) -r $$(OUTPUTDIR)/* $$(SSH_USER)@$$(SSH_HOST):$$(SSH_TARGET_DIR)
-rsync_upload: $$(OUTPUTDIR)/index.html
+rsync_upload: publish
rsync -e "ssh -p $(SSH_PORT)" -P -rvz --delete $(OUTPUTDIR)/* $(SSH_USER)@$(SSH_HOST):$(SSH_TARGET_DIR)
-ftp_upload: $$(OUTPUTDIR)/index.html
+ftp_upload: publish
lftp ftp://$$(FTP_USER)@$$(FTP_HOST) -e "mirror -R $$(OUTPUTDIR) $$(FTP_TARGET_DIR) ; quit"
-github: $$(OUTPUTDIR)/index.html
+github: publish
ghp-import $$(OUTPUTDIR)
git push origin gh-pages
-.PHONY: html help clean ftp_upload ssh_upload rsync_upload dropbox_upload github
+.PHONY: html help clean regenerate serve publish ftp_upload ssh_upload rsync_upload dropbox_upload github
diff --git a/pelican/tools/templates/pelican.conf.py.in b/pelican/tools/templates/pelicanconf.py.in
similarity index 100%
rename from pelican/tools/templates/pelican.conf.py.in
rename to pelican/tools/templates/pelicanconf.py.in
diff --git a/pelican/tools/templates/publishconf.py.in b/pelican/tools/templates/publishconf.py.in
new file mode 100644
index 00000000..391eb9fa
--- /dev/null
+++ b/pelican/tools/templates/publishconf.py.in
@@ -0,0 +1,17 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*- #
+
+from pelicanconf import *
+
+SITEURL = '$siteurl'
+
+DELETE_OUTPUT_DIRECTORY = True
+
+# Following items are often useful when publishing
+
+# Uncomment following line for absolute URLs in production:
+#RELATIVE_URLS = False
+
+#DISQUS_SITENAME = ""
+#GOOGLE_ANALYTICS = ""
+