From 7313d327fb21fbdaa4c39819db6297f4cd635b2c Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Sun, 11 May 2014 18:14:58 -0700 Subject: [PATCH 1/3] Prepare for splitting up Getting Started docs --- docs/{getting_started.rst => content.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{getting_started.rst => content.rst} (100%) diff --git a/docs/getting_started.rst b/docs/content.rst similarity index 100% rename from docs/getting_started.rst rename to docs/content.rst From 86e11c619d0208d9bc8418821c2e2a31e6f991ea Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Mon, 12 May 2014 07:48:37 -0700 Subject: [PATCH 2/3] Split Getting Started docs into separate sections The "Getting Started" docs became overly long and unwieldy over time. This splits it into separate sections, including: * Quickstart * Installation * Writing content * Publish your site --- docs/content.rst | 307 ++-------------------------------------- docs/faq.rst | 12 +- docs/importer.rst | 6 +- docs/index.rst | 22 +-- docs/install.rst | 122 ++++++++++++++++ docs/pelican-themes.rst | 9 -- docs/publish.rst | 174 +++++++++++++++++++++++ docs/quickstart.rst | 73 ++++++++++ docs/settings.rst | 10 +- docs/themes.rst | 18 ++- 10 files changed, 420 insertions(+), 333 deletions(-) create mode 100644 docs/install.rst create mode 100644 docs/publish.rst create mode 100644 docs/quickstart.rst diff --git a/docs/content.rst b/docs/content.rst index 8ee37162..24fc6e9b 100644 --- a/docs/content.rst +++ b/docs/content.rst @@ -1,289 +1,8 @@ -Getting started +Writing content ############### -Installing Pelican -================== - -Pelican currently runs best on Python 2.7.x; earlier versions of Python are -not supported. There is provisional support for Python 3.3, although there may -be rough edges, particularly with regards to optional 3rd-party components. - -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``:: - - $ easy_install pelican - -(Keep in mind that operating systems will often require you to prefix the above -commands with ``sudo`` in order to install Pelican system-wide.) - -While the above is the simplest method, the recommended approach is to create -a virtual environment for Pelican via virtualenv_ before installing Pelican. -Assuming you have virtualenv_ installed, you can then open a new terminal -session and create a new virtual environment for Pelican:: - - $ virtualenv ~/virtualenvs/pelican - $ cd ~/virtualenvs/pelican - $ . bin/activate - -Once the virtual environment has been created and activated, Pelican can be -be installed via ``pip install pelican`` as noted above. Alternatively, if -you have the project source, you can install Pelican using the distutils -method:: - - $ cd path-to-Pelican-source - $ python setup.py install - -If you have Git installed and prefer to install the latest bleeding-edge -version of Pelican rather than a stable release, use the following command:: - - $ pip install -e git+https://github.com/getpelican/pelican.git#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 - -If you want to use AsciiDoc_ you need to install it from `source -`_ or use your operating -system's package manager. - -Basic usage ------------ - -Once Pelican is installed, you can use it to convert your Markdown or reST -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. - -You can also 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. - -Pelican has other command-line switches available. Have a look at the help to -see all the options you can use:: - - $ pelican --help - -Continue reading below for more detail, and check out the Pelican wiki's -`Tutorials `_ page for -links to community-published tutorials. - -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:: - - cd output && python -m SimpleHTTPServer - -Once the ``SimpleHTTPServer`` has been started, you can preview your site at -http://localhost:8000/ - -Upgrading ---------- - -If you installed a stable Pelican release via ``pip`` or ``easy_install`` and -wish to upgrade to the latest stable release, you can do so by adding -``--upgrade`` to the relevant command. For pip, that would be:: - - $ pip install --upgrade pelican - -If you installed Pelican via distutils or the bleeding-edge method, simply -perform the same step to install the most recent version. - -Dependencies ------------- - -When Pelican is installed, the following dependent Python packages should be -automatically installed without any action on your part: - -* `feedgenerator `_, to generate the - Atom feeds -* `jinja2 `_, for templating support -* `pygments `_, for syntax highlighting -* `docutils `_, for supporting - reStructuredText as an input format -* `pytz `_, for timezone definitions -* `blinker `_, an object-to-object and - broadcast signaling system -* `unidecode `_, for ASCII - transliterations of Unicode text -* `six `_, for Python 2 and 3 compatibility - utilities -* `MarkupSafe `_, for a markup safe - string implementation -* `python-dateutil `_, to read - the date metadata - -If you want the following optional packages, you will need to install them -manually via ``pip``: - -* `markdown `_, for supporting Markdown as - an input format -* `typogrify `_, for - typographical enhancements - -Kickstart your site -=================== - -Once Pelican has been installed, you can create a skeleton project via the -``pelican-quickstart`` command, which begins by asking some questions about -your site:: - - $ pelican-quickstart - -Once you finish answering all the questions, your project will consist of the -following hierarchy (except for "pages", which you can optionally add yourself -if you plan to create non-chronological content):: - - yourproject/ - ├── content - │   └── (pages) - ├── output - ├── develop_server.sh - ├── fabfile.py - ├── Makefile - ├── pelicanconf.py # Main settings file - └── publishconf.py # Settings to use when ready to publish - -The next step is to begin to adding content to the *content* folder that has -been created for you. (See the **Writing content using Pelican** section below -for more information about how to format your content.) - -Once you have written some content to generate, you can use the ``pelican`` -command to generate your site, which will be placed in the output folder. - -Automation tools -================ - -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 -described above pertains to whether you want to automate site generation and -publication. If you answered "yes" to that question, a ``fabfile.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. - -Fabric ------- - -The advantage of Fabric_ 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 Fabric, prefixing with -``sudo`` if your environment requires it:: - - $ pip install Fabric - -Take a moment to open the ``fabfile.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:: - - $ fab 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:: - - $ fab regenerate - -To serve the generated site so it can be previewed in your browser at -http://localhost:8000/:: - - $ fab 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:: - - $ fab publish - -These are just a few of the commands available by default, so feel free to -explore ``fabfile.py`` and see what other commands are available. More -importantly, don't hesitate to customize ``fabfile.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, run:: - - $ make html - -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. Once you are done testing your -changes, you should stop the development server via:: - - $ ./develop_server.sh stop - -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. - -(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.) - - -Writing content using Pelican -============================= - Articles and pages ------------------- +================== Pelican considers "articles" to be chronological content, such as posts on a blog, and thus associated with a date. @@ -295,7 +14,7 @@ pages). .. _internal_metadata: 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 @@ -400,7 +119,7 @@ Please note that the metadata available inside your files takes precedence over the metadata extracted from the filename. 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 @@ -416,7 +135,7 @@ things like making error pages that fit the generated theme of your site. .. _ref-linking-to-internal-content: Linking to internal content ---------------------------- +=========================== 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* @@ -494,14 +213,14 @@ curly braces (``{}``). 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. -Importing an existing blog --------------------------- +Importing an existing site +========================== -It is possible to import your blog from Dotclear, WordPress, and RSS feeds using -a simple script. See :ref:`import`. +It is possible to import your site from WordPress, Tumblr, Dotclear, and RSS +feeds using a simple script. See :ref:`import`. Translations ------------- +============ It is possible to translate articles. To do so, you need to add a ``lang`` meta attribute to your articles/pages and set a ``DEFAULT_LANG`` setting (which is @@ -559,7 +278,7 @@ which posts are translations:: .. _internal_pygments_options: Syntax highlighting -------------------- +=================== Pelican is able to provide colorized syntax highlighting for your code blocks. To do so, you have to use the following conventions inside your content files. @@ -641,14 +360,12 @@ If specified, settings for individual code blocks will override the defaults in your settings file. Publishing drafts ------------------ +================= If you want to publish an article as a draft (for friends to review before publishing, for example), you can add a ``Status: draft`` attribute to its metadata. That article will then be output to the ``drafts`` folder and not listed on the index page nor on any category or tag page. -.. _virtualenv: http://www.virtualenv.org/ .. _W3C ISO 8601: http://www.w3.org/TR/NOTE-datetime -.. _Fabric: http://fabfile.org/ .. _AsciiDoc: http://www.methods.co.nz/asciidoc/ diff --git a/docs/faq.rst b/docs/faq.rst index bf468c51..3a5cfec5 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -65,9 +65,11 @@ How do I create my own theme? Please refer to :ref:`theming-pelican`. -I'm using Markdown and getting ``No valid files found in content`` errors. +I want to use Markdown, but I got an error. ========================================================================== +If you try to generate Markdown content without first installing the Markdown +library, may see a message that says ``No valid files found in content``. Markdown is not a hard dependency for Pelican, so if you have content in Markdown format, you will need to explicitly install the Markdown library. You can do so by typing the following command, prepending ``sudo`` if @@ -75,10 +77,6 @@ permissions require it:: pip install markdown -If you don't have ``pip`` installed, consider installing it via:: - - easy_install pip - Can I use arbitrary metadata in my templates? ============================================== @@ -157,8 +155,8 @@ disable all feed generation, you only need to specify the following settings:: CATEGORY_FEED_ATOM = None TRANSLATION_FEED_ATOM = None -Please note that ``None`` and ``''`` are not the same thing. The word ``None`` -should not be surrounded by quotes. +The word ``None`` should not be surrounded by quotes. Please note that ``None`` +and ``''`` are not the same thing. I'm getting a warning about feeds generated without SITEURL being set properly ============================================================================== diff --git a/docs/importer.rst b/docs/importer.rst index b1d1b926..309ca144 100644 --- a/docs/importer.rst +++ b/docs/importer.rst @@ -1,9 +1,7 @@ .. _import: -================================= - Import from other blog software -================================= - +Importing an existing site +########################## Description =========== diff --git a/docs/index.rst b/docs/index.rst index aa30b1f0..36a3282b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,30 +10,32 @@ Pelican |release| Were you looking for version |last_stable| documentation? -Pelican is a static site generator, written in Python_. +Pelican is a static site generator, written in Python_. Highlights include: -* Write your content directly with your editor of choice (vim!) +* Write your content directly with your editor of choice in reStructuredText_, Markdown_, or AsciiDoc_ formats * Includes a simple CLI tool to (re)generate your site * Easy to interface with distributed version control systems and web hooks * Completely static output is easy to host anywhere +Ready to get started? Check out the :doc:`Quickstart` guide. + Features -------- Pelican |version| currently supports: * Articles (e.g., blog posts) and pages (e.g., "About", "Projects", "Contact") -* Comments, via an external service (Disqus). (Please note that while - useful, Disqus is an external service, and thus the comment data will be - somewhat outside of your control and potentially subject to data loss.) +* Comments, via an external service (Disqus). If you prefer to have more + control over your comment data, self-hosted comments are another option. + Check out the `Pelican Plugins`_ repository for more details. * Theming support (themes are created using Jinja2_ templates) * Publication of articles in multiple languages * Atom/RSS feeds * Code syntax highlighting * Import from WordPress, Dotclear, or RSS feeds * Integration with external tools: Twitter, Google Analytics, etc. (optional) -* Fast rebuild times thanks to content caching and selective output writing. +* Fast rebuild times thanks to content caching and selective output writing Why the name "Pelican"? ----------------------- @@ -66,16 +68,19 @@ Documentation .. toctree:: :maxdepth: 2 - getting_started + quickstart + install + content + publish settings themes plugins - internals pelican-themes importer faq tips contribute + internals report changelog @@ -88,5 +93,6 @@ Documentation .. _Jinja2: http://jinja.pocoo.org/ .. _`Pelican documentation`: http://docs.getpelican.com/latest/ .. _`Pelican's internals`: http://docs.getpelican.com/en/latest/internals.html +.. _`Pelican plugins`: https://github.com/getpelican/pelican-plugins .. _`#pelican on Freenode`: irc://irc.freenode.net/pelican .. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4 diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 00000000..34cd33ea --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,122 @@ +Installing Pelican +################## + +Pelican currently runs best on Python 2.7.x; earlier versions of Python are +not supported. There is provisional support for Python 3.3+, although there may +be rough edges, particularly with regards to optional 3rd-party components. + +You can install Pelican via several different methods. The simplest is via +`pip `_:: + + pip install pelican + +(Keep in mind that operating systems will often require you to prefix the above +command with ``sudo`` in order to install Pelican system-wide.) + +While the above is the simplest method, the recommended approach is to create +a virtual environment for Pelican via virtualenv_ before installing Pelican. +Assuming you have virtualenv_ installed, you can then open a new terminal +session and create a new virtual environment for Pelican:: + + virtualenv ~/virtualenvs/pelican + cd ~/virtualenvs/pelican + source bin/activate + +Once the virtual environment has been created and activated, Pelican can be +be installed via ``pip install pelican`` as noted above. Alternatively, if +you have the project source, you can install Pelican using the distutils +method:: + + cd path-to-Pelican-source + python setup.py install + +If you have Git installed and prefer to install the latest bleeding-edge +version of Pelican rather than a stable release, use the following command:: + + pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican" + +Once Pelican is installed, you can run ``pelican --help`` to see basic usage +options. For more detail, refer to the :doc:`Publish` section. + +Optional packages +----------------- + +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 + +If you want to use AsciiDoc_ you need to install it from `source +`_ or use your operating +system's package manager. + +Dependencies +------------ + +When Pelican is installed, the following dependent Python packages should be +automatically installed without any action on your part: + +* `feedgenerator `_, to generate the + Atom feeds +* `jinja2 `_, for templating support +* `pygments `_, for syntax highlighting +* `docutils `_, for supporting + reStructuredText as an input format +* `pytz `_, for timezone definitions +* `blinker `_, an object-to-object and + broadcast signaling system +* `unidecode `_, for ASCII + transliterations of Unicode text +* `six `_, for Python 2 and 3 compatibility + utilities +* `MarkupSafe `_, for a markup safe + string implementation +* `python-dateutil `_, to read + the date metadata + +Upgrading +--------- + +If you installed a stable Pelican release via ``pip`` or ``easy_install`` and +wish to upgrade to the latest stable release, you can do so by adding +``--upgrade`` to the relevant command. For pip, that would be:: + + pip install --upgrade pelican + +If you installed Pelican via distutils or the bleeding-edge method, simply +perform the same step to install the most recent version. + +Kickstart your site +=================== + +Once Pelican has been installed, you can create a skeleton project via the +``pelican-quickstart`` command, which begins by asking some questions about +your site:: + + pelican-quickstart + +Once you finish answering all the questions, your project will consist of the +following hierarchy (except for *pages* — shown in parentheses below — which you +can optionally add yourself if you plan to create non-chronological content):: + + yourproject/ + ├── content + │   └── (pages) + ├── output + ├── develop_server.sh + ├── fabfile.py + ├── Makefile + ├── pelicanconf.py # Main settings file + └── publishconf.py # Settings to use when ready to publish + +The next step is to begin to adding content to the *content* folder that has +been created for you. + +.. _virtualenv: http://www.virtualenv.org/ +.. _AsciiDoc: http://www.methods.co.nz/asciidoc/ diff --git a/docs/pelican-themes.rst b/docs/pelican-themes.rst index 23be8355..7090c648 100644 --- a/docs/pelican-themes.rst +++ b/docs/pelican-themes.rst @@ -153,12 +153,3 @@ The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclus --verbose In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr`` - - - - -See also -======== - -- http://docs.notmyidea.org/alexis/pelican/ -- ``/usr/share/doc/pelican/`` if you have installed Pelican using the `APT repository `_ diff --git a/docs/publish.rst b/docs/publish.rst new file mode 100644 index 00000000..266009e4 --- /dev/null +++ b/docs/publish.rst @@ -0,0 +1,174 @@ +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 +:doc:`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. + +You can also 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. + +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:: + + cd output + python -m SimpleHTTPServer + +Once the ``SimpleHTTPServer`` 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 + +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 +:doc:`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 ``fabfile.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. + +Fabric +------ + +The advantage of Fabric_ 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 Fabric, prefixing with +``sudo`` if your environment requires it:: + + pip install Fabric + +Take a moment to open the ``fabfile.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:: + + fab 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:: + + fab regenerate + +To serve the generated site so it can be previewed in your browser at +http://localhost:8000/:: + + fab 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:: + + fab publish + +These are just a few of the commands available by default, so feel free to +explore ``fabfile.py`` and see what other commands are available. More +importantly, don't hesitate to customize ``fabfile.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, run:: + + make html + +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. Once you are done testing your +changes, you should stop the development server via:: + + ./develop_server.sh stop + +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. + +(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.) + +.. _Fabric: http://fabfile.org/ diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 00000000..44f99dd2 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,73 @@ +Quickstart +########## + +Reading through all the documentation is highly recommended, but for the truly +impatient, following are some quick steps to get started. + +Installation +------------ + +Install Pelican on Python 2.7.x or Python 3.3+ by running the following command +in your preferred terminal, prefixing with ``sudo`` if permissions warrant:: + + pip install pelican markdown + +Create a project +---------------- + +First, choose a name for your project, create an appropriately-named directory +for your it, and switch to that directory:: + + mkdir -p ~/projects/yoursite + cd ~/projects/yoursite + +Create a skeleton project via the ``pelican-quickstart`` command, which begins +by asking some questions about your site:: + + pelican-quickstart + +For questions that have default values denoted in brackets, feel free to use +the Return key to accept those default values. When asked for your URL prefix, +enter your domain name as indicated (e.g., ``http://example.com``). + +Create an article +----------------- + +You cannot run Pelican until you have created some content. Use your preferred +text editor to create your first article with the following content:: + + Title: My First Review + Date: 2010-12-03 10:20 + Category: Review + + Following is a review of my favorite mechanical keyboard. + +Given that this example article is in Markdown format, save it as +``~/projects/yoursite/content/keyboard-review.md``. + +Generate your site +------------------ + +From your project directory, run the ``pelican`` command to generate your site:: + + pelican content + +Your site has now been generated inside the ``output`` directory. (You may see a +warning related to feeds, but that is normal when developing locally and can be +ignored for now.) + +Preview your site +----------------- + +Open a new terminal session and run the following commands to switch to your +``output`` directory and launch Python's built-in web server:: + + cd ~/projects/yoursite/output + python -m SimpleHTTPServer + +Preview your site by navigating to http://localhost:8000/ in your browser. + +Continue reading the other documentation sections for more detail, and check out +the Pelican wiki's Tutorials_ page for links to community-published tutorials. + +.. _Tutorials: https://github.com/getpelican/pelican/wiki/Tutorials diff --git a/docs/settings.rst b/docs/settings.rst index 2782977c..7a69784e 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -1,10 +1,10 @@ Settings ######## -Pelican is configurable thanks to a configuration file you can pass to +Pelican is configurable thanks to a settings file you can pass to the command line:: - $ pelican content -s path/to/your/settingsfile.py + pelican content -s path/to/your/settingsfile.py (If you used the ``pelican-quickstart`` command, your primary settings file will be named ``pelicanconf.py`` by default.) @@ -201,8 +201,8 @@ for URL formation: *relative* and *absolute*. 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 +type of setup, use the ``pelican-quickstart`` script as described in the +:doc:`Installation ` section, 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 @@ -603,7 +603,7 @@ For example:: Translations ============ -Pelican offers a way to translate articles. See the :doc:`Getting Started ` section for +Pelican offers a way to translate articles. See the :doc:`Content ` section for more information. ======================================================== ===================================================== diff --git a/docs/themes.rst b/docs/themes.rst index b029e816..7fcba671 100644 --- a/docs/themes.rst +++ b/docs/themes.rst @@ -1,13 +1,21 @@ .. _theming-pelican: -How to create themes for Pelican -################################ +Creating themes +############### -Pelican uses the great `Jinja2 `_ templating engine to -generate its HTML output. Jinja2 syntax is really simple. If you want to -create your own theme, feel free to take inspiration from the `"simple" theme +To generate its HTML output, Pelican uses the `Jinja `_ +templating engine due to its flexibility and straightforward syntax. If you want +to create your own theme, feel free to take inspiration from the `"simple" theme `_. +To generate your site using a theme you have created (or downloaded manually and +then modified), you can specify that theme via the ``-t`` flag:: + + pelican content -s pelicanconf.py -t /projects/your-site/themes/your-theme + +If you'd rather not specify the theme on every invocation, you can define +``THEME`` in your settings to point to the location of your preferred theme. + Structure ========= From 9d2a129832174c8a65c615148cfbc0a650ecb85c Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Tue, 13 May 2014 07:18:33 -0700 Subject: [PATCH 3/3] If PATH is undefined, Pelican uses PWD as content --- docs/settings.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/settings.rst b/docs/settings.rst index 7a69784e..4701e92d 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -94,7 +94,7 @@ Setting name (followed by default value, if any) ``READERS = {}`` A dictionary of file extensions / Reader classes for Pelican to process or ignore. For example, to avoid processing .html files, set: ``READERS = {'html': None}``. To add a custom reader for the - `foo` extension, set: ``READERS = {'foo': FooReader}`` + ``foo`` extension, set: ``READERS = {'foo': FooReader}`` ``IGNORE_FILES = ['.#*']`` A list of file globbing patterns to match against the source files to be ignored by the processor. For example, the default ``['.#*']`` will ignore emacs lock files. @@ -108,10 +108,12 @@ Setting name (followed by default value, if any) include them explicitly and enumerate the full list of desired Markdown extensions.) ``OUTPUT_PATH = 'output/'`` Where to output the generated files. -``PATH = None`` Path to content directory to be processed by Pelican. -``PAGE_DIR = 'pages'`` Directory to look at for pages, relative to `PATH`. +``PATH`` Path to content directory to be processed by Pelican. If undefined, + and content path is not specified via an argument to the ``pelican`` + command, Pelican will use the current working directory. +``PAGE_DIR = 'pages'`` Directory to look at for pages, relative to ``PATH``. ``PAGE_EXCLUDES = ()`` A list of directories to exclude when looking for pages. -``ARTICLE_DIR = ''`` Directory to look at for articles, relative to `PATH`. +``ARTICLE_DIR = ''`` Directory to look at for articles, relative to ``PATH``. ``ARTICLE_EXCLUDES = ('pages',)`` A list of directories to exclude when looking for articles. ``OUTPUT_SOURCES = False`` Set to True if you want to copy the articles and pages in their original format (e.g. Markdown or reStructuredText) to the