aboutsummaryrefslogblamecommitdiffstats
path: root/readme.rst
blob: 6efd554d8a6538da0f447be8cd7b61c4739f1425 (plain) (tree)






























                                                                                
                                           


               
                                          



























                                                                                 






























































































                                                                             



                                                                          
                                   

























































                                                                              

                                                                               

    





                                                                        


                                                                     
bryanbrattlof.com
##################

This is my `static website's <https://bryanbrattlof.com>`_ theme generated with
`Pelican <https://github.com/getpelican/pelican/>`_.

Motivation
##########

I spend most of my time working on backend things, which means I know
*absolutely nothing* about html/css/js and the unwritten rules of how to combine
them into an elegant website.

So I built this to *learn*.

Installing
##########

The easiest way to install this theme is:

1. **cloning** it into a folder in your project:

.. code-block::

   $ git clone https://gitlab.com/bryanbrattlof/bryanbrattlof.com theme

2. **installing** the plugin dependencies:

* :code:`pelican-webassets` to compile and minify all of the SCSS assets into
  their respective CSS files.

all of which can be installed via pip(env):

.. code-block::

   $ pip install -r theme/requirements.txt


3. and **editing** your pelican settings file, and putting the theme's path
   into the :code:`THEME` setting.

.. code-block:: python

   THEME = 'path/to/theme'

Configuration
#############

An example of the configuration changes needed to build this theme are located in
the :code:`democonf.py`.

*These are their descriptions...*

PLUGINS
=======

To activate the plugins needed to properly build this theme,
you'll need to append the plugins into your :code:`PLUGINS` setting.

.. code-block:: python

   PLUGINS = [
      # ...
      'pelican_webassets',
      # ...
   ]

DIRECT_TEMPLATES
================

This theme has some extra templates that need to be included:

.. code-block:: python

   DIRECT_TEMPLATES = [
       'index',     # root landing page
       'ubad',      # custom 404 page
       'sitemap',   # sitemap.xml
   ]

that will also need their :code:`URL` and :code:`SAVE_AS` settings:

.. code-block:: python

   # sitemap.xml
   SITEMAP_URL = 'sitemap.xml'
   SITEMAP_SAVE_AS = 'sitemap.xml'

   # 404 page
   UBAD_URL = '404/'
   UBAD_SAVE_AS = UBAD_URL + 'index.html'

WEBASSETS_SOURCE_PATHS
======================

Because the SCSS assets aren't located inside the :code:`THEME_STATIC_PATHS`
directory, we have to add the folder to the assets ourselves.

.. code-block:: python

    WEBASSETS_SOURCE_PATHS = ['stylesheets']

WEBASSETS_BUNDLES
=================

To make things simpler (on me, not you) I've defined several
:code:`webasset.Bundles` to compile the SCSS assets into their minifed CSS
output.

More information about these bundles is provided in the `pelican-webassets
<https://pypi.org/project/pelican-webassets/>`_ README

.. code-block:: python

   WEBASSETS_BUNDLES = (
       (
           'articles_css', (
               'article.scss',
           ), {
               'output': 'css/article.css',
               'filters': [
                   'libsass',
               ]
           }
       ), (
           'indexes_css', (
               'index.scss',
           ), {
               'output': 'css/index.css',
               'filters': [
                   'libsass',
               ]
           }
       ), (
           '404_css', (
               'ubad.scss',
           ), {
               'output': 'css/404.css',
               'filters': [
                   'libsass',
               ]
           }
       ),
   )

WEBASSETS_CONFIG
================

:code:`webassets` uses :code:`libsass` to compile the SCSS files for
us. However by default, :code:`libsass` will not compress the files. Adding a
line to :code:`WEBASSETS_CONFIG` will allow :code:`libsass` to minify the
files as well as compile them.

.. code-block:: python

   WEBASSETS_CONFIG = (
       ('libsass_style', 'compressed'),
   )

META_LINKS
==========

(optional) A list of items you wish to add a :code:`<link>` element to the
:code:`<head>` block of every page.

.. code-block:: python

   META_LINKS = (
       {
           'rel': 'icon', 'sizes': '32x32', 'type': 'image/png',
           'href': SITEURL + '/static/img/favicon-32x32.png'))
       },{
           'rel': 'manifest',
           'href': SITEURL + '/static/site.webmanifest'))
       }
   )


TWITTER_HANDLE
==============

(optional) The twitter profile you wish to supply for the :code:`twitter:site`
in the Twitter cards.

.. code-block:: python

   TWITTER_HANDLE = '@bryanbrattlof'

LOGO_IMAGE
==========

(optional) The image you wish to use as your signature at the bottom of every
page's footer.

.. code-block:: python

   LOGO_IMAGE = 'static/img/logo.png'

LINKS
=====

(optional) A list of tuples in the form of :code:`(name, url)` for the links
you wish to include in the footer of every page.

.. code-block:: python

   LINKS = (
       ('Home', ''),
       ('About', PAGE_URL.format(slug='hi')),
       ('Connect', PAGE_URL.format(slug='connect')),
       ('Support', PAGE_URL.format(slug='support')),
   )

LICENSE
=======

(optional) The license in :code:`(name, url)` form you wish to include in the
footer of every page.

.. code-block:: python

   LICENSE = (
       'Creative Commons Attribution-NonCommercial 4.0 International License.',
       'https://creativecommons.org/licenses/by-nc/4.0',
   )

Want to Help?
#############

Please feel free to help. Issues, pull requests, even patches `via email
<https://bryanbrattlof.com/connect/>`_, all are warmly welcomed.

.. image:: https://img.shields.io/badge/License-WTFPL-brightgreen.svg
   :target: http://www.wtfpl.net/about/
   :alt: License: WTFPL