mirror of
https://github.com/vale981/ablog
synced 2025-03-05 17:21:38 -05:00
125 lines
3.6 KiB
ReStructuredText
125 lines
3.6 KiB
ReStructuredText
.. _quick-start:
|
|
|
|
|
|
ABlog Quick Start
|
|
=================
|
|
|
|
.. post:: Mar 1, 2015
|
|
:tags: config, tips
|
|
:author: Mehmet, Ahmet
|
|
:category: Manual
|
|
:location: SF
|
|
|
|
This short walk through of blogging work flow assumes that you have already
|
|
installed ABlog. If not, see :ref:`installation` guide.
|
|
|
|
*Note that this post is a working draft. Feel free to revise it on GitHub.*
|
|
|
|
Start a Project
|
|
---------------
|
|
|
|
To start a new project, run ``ablog start`` command in a directory where
|
|
you want to keep your project source files. This command will ask you a
|
|
few questions and create the following files:
|
|
|
|
* :file:`conf.py` that contains project configuration for building HTML
|
|
pages.
|
|
|
|
* :file:`first-post.rst`, a blog post example.
|
|
|
|
* :file:`index.rst` that contains content for the *landing* page of your
|
|
website.
|
|
|
|
* :file:`about.rst`, another non-post page example.
|
|
|
|
|
|
|
|
Build and View
|
|
--------------
|
|
|
|
With no further delay, let's see what your project will look like.
|
|
First run ``ablog build``, in your project folder, to have HTML pages
|
|
built in :file:`_website` folder. Then, call ``ablog serve`` to view
|
|
them in your default web browser. See :ref:`commands` for more
|
|
information about these commands.
|
|
|
|
Your landing page is built from :file:`index.rst` and contains links to your
|
|
first post and about page. Take a look at :file:`index.rst` for some tips on
|
|
navigation links within the project.
|
|
|
|
|
|
Write Content
|
|
-------------
|
|
|
|
If you are new to Sphinx_ and reStructuredText markup language,
|
|
you might find `reStructuredText Primer`_ useful.
|
|
|
|
.. _reStructuredText Primer: http://sphinx-doc.org/rest.html
|
|
|
|
|
|
Pages
|
|
^^^^^
|
|
|
|
Pages in your project are :file:`.rst` files that are only a :rst:dir:`post`
|
|
directive short of becoming blog posts. To make regular pages accessible
|
|
from the navigation bar, you need to list them in a :rst:dir:`toctree`.
|
|
This is shown for *about* page into :file:`index.rst`.
|
|
|
|
Posts
|
|
^^^^^
|
|
|
|
You can convert any page to a post with a :rst:dir:`post` directive.
|
|
ABlog will take care of listing posts in specified archives and sidebars.
|
|
|
|
|
|
Comments
|
|
--------
|
|
|
|
You can enable comments in your website by creating a Disqus_ account and
|
|
obtaining a unique identifier, i.e. :confval:`disqus_shortname`.
|
|
See :ref:`disqus-integration` for configuration options.
|
|
|
|
Analytics
|
|
---------
|
|
|
|
ABlog uses Alabaster_ theme by default. You can use theme options to set
|
|
your `Google Analytics`_ identifier to enable tracking.
|
|
|
|
.. _Google Analytics: http://www.google.com/analytics/
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
There are four major groups of configuration options that can help you
|
|
customize how your website looks:
|
|
|
|
* :ref:`config` - add blog authors, post locations and languages to your
|
|
blog, adjust archive and feed content, etc.
|
|
|
|
* `General configuration <http://sphinx-doc.org/config.html#general-configuration>`_
|
|
and `project information <http://sphinx-doc.org/config.html#project-information>`_
|
|
|
|
|
|
* :ref:`html-options` - configure appearance of your website
|
|
|
|
* Alabaster_ theme options - link to your GitHub account and project, set up
|
|
tracking, etc.
|
|
|
|
|
|
Other Folders
|
|
-------------
|
|
|
|
You might have noticed that your project contains three folders that we have
|
|
not mention yet. Here they are:
|
|
|
|
* :file:`_static` is for keeping image, :file:`.js`, and :file:`.css` files.
|
|
:confval:`html_static_path` Sphinx option for more information.
|
|
|
|
* :file:`_templates` is for custom HTML templates. See
|
|
:confval:`templates_path` for more information.
|
|
|
|
* :file:`.doctree` folder, created after build command is called, is
|
|
where Sphinx_ stores the state of your project. Files in this folder
|
|
saves time when you rebuild your project.
|
|
|
|
|