Fix themeing docs
This fixes a bunch of formatting issues in the themeing docs and makes them easier to read.
This commit is contained in:
Will Kahn-Greene
parent
54b42ee564
commit
8464bcc3e8
@ -25,32 +25,32 @@ support! This guide should walk you through installing and making themes.
|
||||
|
||||
|
||||
Installing a theme
|
||||
------------------
|
||||
==================
|
||||
|
||||
Installing the archive
|
||||
======================
|
||||
----------------------
|
||||
|
||||
Say you have a theme archive such as goblincities.tar.gz. You want to
|
||||
install this theme! Don't worry, it's fairly painless.
|
||||
|
||||
Simply cd to the "install directory" for themes (by default,
|
||||
./user_dev/themes/ relative to the mediagoblin install directory... to
|
||||
``./user_dev/themes/`` relative to the mediagoblin install directory... to
|
||||
configure these things, see the next section), move the archive there,
|
||||
and decompress.
|
||||
and decompress::
|
||||
|
||||
tar xvfz goblincities.tar.gz
|
||||
$ tar xvfz goblincities.tar.gz
|
||||
|
||||
Next, open up your mediagoblin configuration file (probably
|
||||
mediagoblin_local.ini) and set the theme name:
|
||||
``mediagoblin_local.ini``) and set the theme name::
|
||||
|
||||
[mediagoblin]
|
||||
# ...
|
||||
theme = goblincities
|
||||
[mediagoblin]
|
||||
# ...
|
||||
theme = goblincities
|
||||
|
||||
Finally, "link the assets" so that they can be served by your web
|
||||
server.
|
||||
server::
|
||||
|
||||
./bin/gmg theme assetlink
|
||||
$ ./bin/gmg theme assetlink
|
||||
|
||||
Note, if you ever change the current theme in your config file, you
|
||||
should re-run the above command!
|
||||
@ -59,56 +59,59 @@ should re-run the above command!
|
||||
|
||||
.. In the future, this might look more like:
|
||||
.. Installing a theme in MediaGoblin is fairly easy! Assuming you
|
||||
.. already have a theme package, just do this:
|
||||
|
||||
.. $ ./bin/gmg theme install --fullsetup goblincities.tar.gz
|
||||
|
||||
.. already have a theme package, just do this::
|
||||
..
|
||||
.. $ ./bin/gmg theme install --fullsetup goblincities.tar.gz
|
||||
..
|
||||
.. This would install the theme, set it as current, and symlink its
|
||||
.. assets.
|
||||
|
||||
|
||||
Set up your webserver to serve theme assets
|
||||
===========================================
|
||||
-------------------------------------------
|
||||
|
||||
Section to be written, ask on #mediagoblin in irc.freenode.net in the
|
||||
meanwhile ;)
|
||||
|
||||
|
||||
Configuring where things go
|
||||
===========================
|
||||
---------------------------
|
||||
|
||||
By default, MediaGoblin's install directory for themes is
|
||||
./user_dev/themes/ (relative to the MediaGoblin checkout or base
|
||||
config file.) However, you can change this location easily. In your
|
||||
mediagoblin config file, under the section [mediagoblin] set the
|
||||
following parameter:
|
||||
following parameter::
|
||||
|
||||
[mediagoblin]
|
||||
# ... other parameters go here ...
|
||||
theme_install_dir = /path/to/themes/
|
||||
[mediagoblin]
|
||||
# ... other parameters go here ...
|
||||
theme_install_dir = /path/to/themes/
|
||||
|
||||
Other variables you may consider setting:
|
||||
|
||||
- theme_web_path: when theme-specific assets are specified, this is
|
||||
where MediaGoblin will set the urls. By default this is
|
||||
"/theme_static/" so in the case that your theme was trying to
|
||||
access its file "images/shiny_button.png" MediaGoblin would link
|
||||
to /theme_static/images/shiny_button.png
|
||||
- theme_linked_assets_dir: Your web server needs to serve the theme
|
||||
files out of some directory, and MediaGoblin will symlink the
|
||||
current theme's assets here. (See "Linking assets" in the theme
|
||||
install section)
|
||||
`theme_web_path`
|
||||
When theme-specific assets are specified, this is where MediaGoblin
|
||||
will set the urls. By default this is ``"/theme_static/"`` so in
|
||||
the case that your theme was trying to access its file
|
||||
``"images/shiny_button.png"`` MediaGoblin would link
|
||||
to ``/theme_static/images/shiny_button.png``.
|
||||
|
||||
`theme_linked_assets_dir`
|
||||
Your web server needs to serve the theme files out of some directory,
|
||||
and MediaGoblin will symlink the current theme's assets here. (See
|
||||
"Linking assets" in the theme install section)
|
||||
|
||||
|
||||
Making a theme
|
||||
--------------
|
||||
==============
|
||||
|
||||
Okay, so a theme layout is pretty simple. Let's assume we're making a
|
||||
theme for an instance about hedgehogs! We'll call this the
|
||||
"hedgehogified" theme.
|
||||
|
||||
Change to where your theme_install_dir is set to (by default,
|
||||
./user_dev/themes/ ... make those directories if necessary and
|
||||
otherwise adjust if necessary)
|
||||
``./user_dev/themes/`` ... make those directories if necessary and
|
||||
otherwise adjust if necessary)::
|
||||
|
||||
hedgehogified/
|
||||
|- theme.cfg # configuration file for this theme
|
||||
@ -126,6 +129,7 @@ otherwise adjust if necessary)
|
||||
|- AGPLv3.txt # AGPL license file for your theme. (good practice)
|
||||
'- CC0_1.0.txt # CC0 1.0 legalcode for the assets [if appropriate!]
|
||||
|
||||
|
||||
The top level directory of your theme should be the symbolic name for
|
||||
your theme. This is the name that users will use to refer to activate
|
||||
your theme.
|
||||
@ -136,16 +140,17 @@ itself. However, all the rest of your assets are up to you. In this
|
||||
case, we are waiving our copyright for images and CSS into the public
|
||||
domain via CC0 (as MediaGoblin does) but do what's appropriate to you.
|
||||
|
||||
|
||||
The config file
|
||||
===============
|
||||
|
||||
The config file is not presently strictly required, though it is nice to have.
|
||||
Only a few things need to go in here.
|
||||
Only a few things need to go in here::
|
||||
|
||||
[theme]
|
||||
name = Hedgehog-ification
|
||||
description = For hedgehog lovers ONLY
|
||||
licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0
|
||||
[theme]
|
||||
name = Hedgehog-ification
|
||||
description = For hedgehog lovers ONLY
|
||||
licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0
|
||||
|
||||
The name and description fields here are to give users an idea of what
|
||||
your theme is about. For the moment, we don't have any listing
|
||||
@ -158,13 +163,13 @@ specify whatever is appropriate to your assets.
|
||||
|
||||
|
||||
Templates
|
||||
=========
|
||||
---------
|
||||
|
||||
Your template directory is where you can put any override and custom
|
||||
templates for MediaGoblin.
|
||||
|
||||
These follow the general MediaGoblin theming layout, which means that
|
||||
the MediaGoblin core templates are all kept under the ./mediagoblin/
|
||||
the MediaGoblin core templates are all kept under the ``./mediagoblin/``
|
||||
prefix directory.
|
||||
|
||||
You can copy files right out of MediaGoblin core and modify them in
|
||||
@ -172,34 +177,34 @@ this matter if you wish.
|
||||
|
||||
To fit with best licensing form, you should either preserve the
|
||||
MediaGoblin copyright header borrowing from a MediaGoblin template, or
|
||||
you may include one like the following if a new file:
|
||||
you may include one like the following if a new file::
|
||||
|
||||
{#
|
||||
# [YOUR THEME], a MediaGoblin theme
|
||||
# Copyright (C) [YEAR] [YOUR NAME]
|
||||
#
|
||||
# This program is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU Affero General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# This program is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU Affero General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU Affero General Public License
|
||||
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
#}
|
||||
{#
|
||||
# [YOUR THEME], a MediaGoblin theme
|
||||
# Copyright (C) [YEAR] [YOUR NAME]
|
||||
#
|
||||
# This program is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU Affero General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# This program is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU Affero General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU Affero General Public License
|
||||
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
#}
|
||||
|
||||
|
||||
Assets
|
||||
=======
|
||||
------
|
||||
|
||||
Put any files, such as images, CSS, etc, that are specific to your
|
||||
theme in here.
|
||||
|
||||
You can reference these in your templates like so:
|
||||
You can reference these in your templates like so::
|
||||
|
||||
<img src="{{ request.staticdirect('/images/im_a_shark.png', 'theme') }}" />
|
||||
|
||||
@ -207,17 +212,17 @@ This will tell MediaGoblin to reference this image from the current theme.
|
||||
|
||||
|
||||
Licensing file(s)
|
||||
=================
|
||||
-----------------
|
||||
|
||||
You should include AGPLv3.txt with your theme as this is required for
|
||||
the assets. You can copy this from mediagoblin/licenses/
|
||||
the assets. You can copy this from ``mediagoblin/licenses/``.
|
||||
|
||||
In the above example, we also use CC0 to waive our copyrights to
|
||||
images and css, so we also included CC0_1.0.txt
|
||||
|
||||
|
||||
A README.txt file
|
||||
=================
|
||||
-----------------
|
||||
|
||||
A readme file is not strictly required, but probably a good idea. You
|
||||
can put whatever in here, but restating the license choice clearly is
|
||||
@ -225,21 +230,21 @@ probably a good idea.
|
||||
|
||||
|
||||
Simple theming by adding CSS
|
||||
============================
|
||||
----------------------------
|
||||
|
||||
Many themes won't require anything other than the ability to override
|
||||
some of MediaGoblin's core css. Thankfully, doing so is easy if you
|
||||
combine the above steps!
|
||||
|
||||
In your theme, do the following (make sure you make the necessary
|
||||
directories and cd to your theme's directory first):
|
||||
directories and cd to your theme's directory first)::
|
||||
|
||||
$ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/
|
||||
$ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/
|
||||
|
||||
Great, now open that file and add something like this at the end:
|
||||
Great, now open that file and add something like this at the end::
|
||||
|
||||
<link rel="stylesheet" type="text/css"
|
||||
href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/>
|
||||
<link rel="stylesheet" type="text/css"
|
||||
href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/>
|
||||
|
||||
You can name the css file whatever you like. Now make the directory
|
||||
for assets/css/ and add the file assets/css/theme.css
|
||||
@ -249,13 +254,13 @@ override default MediaGoblin CSS.
|
||||
|
||||
|
||||
Packaging it up!
|
||||
================
|
||||
----------------
|
||||
|
||||
Packaging a theme is really easy. It's just a matter of making an archive!
|
||||
|
||||
Change to the installed themes directory and run the following:
|
||||
Change to the installed themes directory and run the following::
|
||||
|
||||
tar cvfz yourtheme.tar.gz yourtheme
|
||||
tar cvfz yourtheme.tar.gz yourtheme
|
||||
|
||||
Where "yourtheme" is replaced with your theme name.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user