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 = "" +