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:
parent
54b42ee564
commit
8464bcc3e8
@ -25,32 +25,32 @@ support! This guide should walk you through installing and making themes.
|
|||||||
|
|
||||||
|
|
||||||
Installing a theme
|
Installing a theme
|
||||||
------------------
|
==================
|
||||||
|
|
||||||
Installing the archive
|
Installing the archive
|
||||||
======================
|
----------------------
|
||||||
|
|
||||||
Say you have a theme archive such as goblincities.tar.gz. You want to
|
Say you have a theme archive such as goblincities.tar.gz. You want to
|
||||||
install this theme! Don't worry, it's fairly painless.
|
install this theme! Don't worry, it's fairly painless.
|
||||||
|
|
||||||
Simply cd to the "install directory" for themes (by default,
|
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,
|
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
|
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]
|
[mediagoblin]
|
||||||
# ...
|
# ...
|
||||||
theme = goblincities
|
theme = goblincities
|
||||||
|
|
||||||
Finally, "link the assets" so that they can be served by your web
|
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
|
Note, if you ever change the current theme in your config file, you
|
||||||
should re-run the above command!
|
should re-run the above command!
|
||||||
@ -59,28 +59,29 @@ should re-run the above command!
|
|||||||
|
|
||||||
.. In the future, this might look more like:
|
.. In the future, this might look more like:
|
||||||
.. Installing a theme in MediaGoblin is fairly easy! Assuming you
|
.. Installing a theme in MediaGoblin is fairly easy! Assuming you
|
||||||
.. already have a theme package, just do this:
|
.. already have a theme package, just do this::
|
||||||
|
..
|
||||||
.. $ ./bin/gmg theme install --fullsetup goblincities.tar.gz
|
.. $ ./bin/gmg theme install --fullsetup goblincities.tar.gz
|
||||||
|
..
|
||||||
.. This would install the theme, set it as current, and symlink its
|
.. This would install the theme, set it as current, and symlink its
|
||||||
.. assets.
|
.. assets.
|
||||||
|
|
||||||
|
|
||||||
Set up your webserver to serve theme assets
|
Set up your webserver to serve theme assets
|
||||||
===========================================
|
-------------------------------------------
|
||||||
|
|
||||||
Section to be written, ask on #mediagoblin in irc.freenode.net in the
|
Section to be written, ask on #mediagoblin in irc.freenode.net in the
|
||||||
meanwhile ;)
|
meanwhile ;)
|
||||||
|
|
||||||
|
|
||||||
Configuring where things go
|
Configuring where things go
|
||||||
===========================
|
---------------------------
|
||||||
|
|
||||||
By default, MediaGoblin's install directory for themes is
|
By default, MediaGoblin's install directory for themes is
|
||||||
./user_dev/themes/ (relative to the MediaGoblin checkout or base
|
./user_dev/themes/ (relative to the MediaGoblin checkout or base
|
||||||
config file.) However, you can change this location easily. In your
|
config file.) However, you can change this location easily. In your
|
||||||
mediagoblin config file, under the section [mediagoblin] set the
|
mediagoblin config file, under the section [mediagoblin] set the
|
||||||
following parameter:
|
following parameter::
|
||||||
|
|
||||||
[mediagoblin]
|
[mediagoblin]
|
||||||
# ... other parameters go here ...
|
# ... other parameters go here ...
|
||||||
@ -88,27 +89,29 @@ following parameter:
|
|||||||
|
|
||||||
Other variables you may consider setting:
|
Other variables you may consider setting:
|
||||||
|
|
||||||
- theme_web_path: when theme-specific assets are specified, this is
|
`theme_web_path`
|
||||||
where MediaGoblin will set the urls. By default this is
|
When theme-specific assets are specified, this is where MediaGoblin
|
||||||
"/theme_static/" so in the case that your theme was trying to
|
will set the urls. By default this is ``"/theme_static/"`` so in
|
||||||
access its file "images/shiny_button.png" MediaGoblin would link
|
the case that your theme was trying to access its file
|
||||||
to /theme_static/images/shiny_button.png
|
``"images/shiny_button.png"`` MediaGoblin would link
|
||||||
- theme_linked_assets_dir: Your web server needs to serve the theme
|
to ``/theme_static/images/shiny_button.png``.
|
||||||
files out of some directory, and MediaGoblin will symlink the
|
|
||||||
current theme's assets here. (See "Linking assets" in the theme
|
`theme_linked_assets_dir`
|
||||||
install section)
|
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
|
Making a theme
|
||||||
--------------
|
==============
|
||||||
|
|
||||||
Okay, so a theme layout is pretty simple. Let's assume we're making a
|
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
|
theme for an instance about hedgehogs! We'll call this the
|
||||||
"hedgehogified" theme.
|
"hedgehogified" theme.
|
||||||
|
|
||||||
Change to where your theme_install_dir is set to (by default,
|
Change to where your theme_install_dir is set to (by default,
|
||||||
./user_dev/themes/ ... make those directories if necessary and
|
``./user_dev/themes/`` ... make those directories if necessary and
|
||||||
otherwise adjust if necessary)
|
otherwise adjust if necessary)::
|
||||||
|
|
||||||
hedgehogified/
|
hedgehogified/
|
||||||
|- theme.cfg # configuration file for this theme
|
|- 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)
|
|- AGPLv3.txt # AGPL license file for your theme. (good practice)
|
||||||
'- CC0_1.0.txt # CC0 1.0 legalcode for the assets [if appropriate!]
|
'- 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
|
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. This is the name that users will use to refer to activate
|
||||||
your theme.
|
your theme.
|
||||||
@ -136,11 +140,12 @@ 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
|
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.
|
domain via CC0 (as MediaGoblin does) but do what's appropriate to you.
|
||||||
|
|
||||||
|
|
||||||
The config file
|
The config file
|
||||||
===============
|
===============
|
||||||
|
|
||||||
The config file is not presently strictly required, though it is nice to have.
|
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]
|
[theme]
|
||||||
name = Hedgehog-ification
|
name = Hedgehog-ification
|
||||||
@ -158,13 +163,13 @@ specify whatever is appropriate to your assets.
|
|||||||
|
|
||||||
|
|
||||||
Templates
|
Templates
|
||||||
=========
|
---------
|
||||||
|
|
||||||
Your template directory is where you can put any override and custom
|
Your template directory is where you can put any override and custom
|
||||||
templates for MediaGoblin.
|
templates for MediaGoblin.
|
||||||
|
|
||||||
These follow the general MediaGoblin theming layout, which means that
|
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.
|
prefix directory.
|
||||||
|
|
||||||
You can copy files right out of MediaGoblin core and modify them in
|
You can copy files right out of MediaGoblin core and modify them in
|
||||||
@ -172,7 +177,7 @@ this matter if you wish.
|
|||||||
|
|
||||||
To fit with best licensing form, you should either preserve the
|
To fit with best licensing form, you should either preserve the
|
||||||
MediaGoblin copyright header borrowing from a MediaGoblin template, or
|
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
|
# [YOUR THEME], a MediaGoblin theme
|
||||||
@ -194,12 +199,12 @@ you may include one like the following if a new file:
|
|||||||
|
|
||||||
|
|
||||||
Assets
|
Assets
|
||||||
=======
|
------
|
||||||
|
|
||||||
Put any files, such as images, CSS, etc, that are specific to your
|
Put any files, such as images, CSS, etc, that are specific to your
|
||||||
theme in here.
|
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') }}" />
|
<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)
|
Licensing file(s)
|
||||||
=================
|
-----------------
|
||||||
|
|
||||||
You should include AGPLv3.txt with your theme as this is required for
|
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
|
In the above example, we also use CC0 to waive our copyrights to
|
||||||
images and css, so we also included CC0_1.0.txt
|
images and css, so we also included CC0_1.0.txt
|
||||||
|
|
||||||
|
|
||||||
A README.txt file
|
A README.txt file
|
||||||
=================
|
-----------------
|
||||||
|
|
||||||
A readme file is not strictly required, but probably a good idea. You
|
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
|
can put whatever in here, but restating the license choice clearly is
|
||||||
@ -225,18 +230,18 @@ probably a good idea.
|
|||||||
|
|
||||||
|
|
||||||
Simple theming by adding CSS
|
Simple theming by adding CSS
|
||||||
============================
|
----------------------------
|
||||||
|
|
||||||
Many themes won't require anything other than the ability to override
|
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
|
some of MediaGoblin's core css. Thankfully, doing so is easy if you
|
||||||
combine the above steps!
|
combine the above steps!
|
||||||
|
|
||||||
In your theme, do the following (make sure you make the necessary
|
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"
|
<link rel="stylesheet" type="text/css"
|
||||||
href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/>
|
href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/>
|
||||||
@ -249,11 +254,11 @@ override default MediaGoblin CSS.
|
|||||||
|
|
||||||
|
|
||||||
Packaging it up!
|
Packaging it up!
|
||||||
================
|
----------------
|
||||||
|
|
||||||
Packaging a theme is really easy. It's just a matter of making an archive!
|
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
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user