ABlog Quick Start¶

This short walk through of blogging work flow assumes that you have already installed ABlog. If not, see 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:

conf.py that contains project configuration for building HTML pages.

first-post.rst, a blog post example.

index.rst that contains content for the landing page of your website.

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 _website folder. Then, call ablog serve to view them in your default web browser. See ABlog Commands for more information about these commands.

Your landing page is built from index.rst and contains links to your first post and about page. Take a look at 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.

Pages¶

Pages in your project are .rst files that are only a post directive short of becoming blog posts. To make regular pages accessible from the navigation bar, you need to list them in a toctree. This is shown for about page into index.rst.

Posts¶

You can convert any page to a post with a post directive. ABlog will take care of listing posts in specified archives and sidebars.

Blog posts¶

You can start new blog posts with either a front-matter or a directive using ABlog. Simply use something based on the following template as the front-matter:

:blogpost: true
:date: January 1, 2020
:author: A. Author
:location: World
:category: Blog
:language: English
:tags: blog

Simply use something based on the following template as the directive for ABlog:

.. post:: January 1, 2020

  :author: A. Author
  :location: World
  :category: Blog
  :language: English
  :tags: blog

For more information, see Posting with a Directive and Posting with page front-matter.

Comments¶

You can enable comments in your website by creating a Disqus account and obtaining a unique identifier, i.e. disqus_shortname. See 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.

Configuration¶

There are four major groups of configuration options that can help you customize how your website looks:

ABlog Configuration Options - add blog authors, post locations and languages to your blog, adjust archive and feed content, etc.

General configuration and project information

Options for HTML output - 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:

_static is for keeping image, .js, and .css files. html_static_path Sphinx option for more information.

_templates is for custom HTML templates. See templates_path for more information.

.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.

ABlog Commands ABlog v0.5 released

Comments

comments powered by Disqus