diff --git a/docs/_static/theme-basic.zip b/docs/_static/theme-basic.zip deleted file mode 100644 index d1e4754a..00000000 Binary files a/docs/_static/theme-basic.zip and /dev/null differ diff --git a/docs/themes.rst b/docs/themes.rst index fa4c9d37..c17d0fbd 100644 --- a/docs/themes.rst +++ b/docs/themes.rst @@ -589,38 +589,12 @@ using the ``{% extends %}`` directive as in the following example: Example ------- -With this system, it is possible to create a theme with just two files. +With this system, it is possible to create a theme with just one file. -base.html -""""""""" +main.css +"""""""" -The first file is the ``templates/base.html`` template: - -.. code-block:: html+jinja - - {% extends "!simple/base.html" %} - - {% block head %} - {{ super() }} - - {% endblock %} - -1. On the first line, we extend the ``base.html`` template from the ``simple`` - theme, so we don't have to rewrite the entire file. -2. On the third line, we open the ``head`` block which has already been defined - in the ``simple`` theme. -3. On the fourth line, the function ``super()`` keeps the content previously - inserted in the ``head`` block. -4. On the fifth line, we append a stylesheet to the page. -5. On the last line, we close the ``head`` block. - -This file will be extended by all the other templates, so the stylesheet will -be linked from all pages. - -style.css -""""""""" - -The second file is the ``static/css/style.css`` CSS stylesheet: +The file is ``static/css/main.css`` (the default ``CSS_FILE``): .. code-block:: css @@ -663,10 +637,32 @@ The second file is the ``static/css/style.css`` CSS stylesheet: margin-top : 1em ; } -Download -"""""""" +Custom templates +"""""""""""""""" -You can download this example theme :download:`here <_static/theme-basic.zip>`. +If you want to customise the templates as well, you can extend them. For +example, to add a custom footer, create a ``templates/base.html``: + +.. code-block:: html+jinja + + {% extends "!simple/base.html" %} + + {% block footer %} +
Custom footer
+ {{ super() }} + {% endblock %} + +1. On the first line, we extend the ``base.html`` template from the ``simple`` + theme, so we don't have to rewrite the entire file. +2. On the third line, we open the ``footer`` block which has already been + defined in the ``simple`` theme. +3. On the fourth line, we insert the extra footer content. +4. On the fifth line, the function ``super()`` keeps the content previously + inserted in the ``head`` block. +5. On the last line, we close the ``footer`` block. + +This file will be extended by all the other templates, so the custom footer +will appear on all pages. .. Links diff --git a/pelican/tests/test_theme.py b/pelican/tests/test_theme.py index 4e47eb2a..7012b2e4 100644 --- a/pelican/tests/test_theme.py +++ b/pelican/tests/test_theme.py @@ -218,5 +218,42 @@ class TestTemplateInheritance(LoggedTestCase): content, ) + def test_css_only_theme(self): + """A theme with only a static/css/main.css file (no templates) + should work by falling back to the simple theme's templates.""" + + css_only_theme = mkdtemp(prefix="pelican_test_css_only_theme.") + css_dir = os.path.join(css_only_theme, "static", "css") + os.makedirs(css_dir) + with open(os.path.join(css_dir, "main.css"), "w") as f: + f.write("body { margin: 0; }") + + try: + settings = read_settings( + path=None, + override={ + "THEME": css_only_theme, + "PATH": CONTENT_DIR, + "OUTPUT_PATH": self.temp_output, + "CACHE_PATH": self.temp_cache, + "SITEURL": "http://example.com", + }, + ) + + pelican = Pelican(settings=settings) + mute(True)(pelican.run)() + + with open(os.path.join(self.temp_output, "test-md-file.html")) as f: + content = f.read() + + self.assertIn( + 'href="http://example.com/theme/css/main.css"', + content, + ) + self.assertIn("Proudly powered by", content) + finally: + rmtree(css_only_theme) + + if __name__ == "__main__": unittest.main()