Split Archive into Index and Archive

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [unreleased]
+
+* **Breaking Change**: Split former archive page which served as index.html
+  into "index" and "archive", each with their own template, respectively. Index
+  is the landing page and shows by default only the latest 10 articles. Archive
+  shows the full list of articles.
+
+  If you used custom templates,
+    * you should create an "index.html"-template (take blag's default one as a
+      starting point)
+    * you may want to include the new "/archive.html" link somewhere in your
+      navigation
+
 ## [1.5.0] - 2023-04-16
 
 * moved to pyproject.toml

blag/blag.py

@@ -263,6 +263,7 @@ def build(args: argparse.Namespace) -> None:
 
     page_template = env.get_template('page.html')
     article_template = env.get_template('article.html')
+    index_template = env.get_template('index.html')
     archive_template = env.get_template('archive.html')
     tags_template = env.get_template('tags.html')
     tag_template = env.get_template('tag.html')
@@ -283,6 +284,7 @@ def build(args: argparse.Namespace) -> None:
         blog_description=config['description'],
         blog_author=config['author'],
     )
+    generate_index(articles, index_template, args.output_dir)
     generate_archive(articles, archive_template, args.output_dir)
     generate_tags(articles, tags_template, tag_template, args.output_dir)
 
@@ -302,6 +304,8 @@ def process_markdown(
     If a markdown file has a `date` metadata field it will be recognized
     as article otherwise as page.
 
+    Articles are sorted by date in descending order.
+
     Parameters
     ----------
     convertibles
@@ -309,12 +313,12 @@ def process_markdown(
     input_dir
     output_dir
     page_template, archive_template
-        templats for pages and articles
+        templates for pages and articles
 
     Returns
     -------
     list[tuple[str, dict[str, Any]]], list[tuple[str, dict[str, Any]]]
-        articles and pages
+        articles and pages, articles are sorted by date in descending order.
 
     """
     logger.info("Converting Markdown files...")
@@ -401,12 +405,14 @@ def generate_feed(
         feed.write(fh, encoding='utf8')
 
 
-def generate_archive(
+def generate_index(
     articles: list[tuple[str, dict[str, Any]]],
     template: Template,
     output_dir: str,
 ) -> None:
-    """Generate the archive page.
+    """Generate the index page.
+
+    This is used for the index (i.e. landing) page.
 
     Parameters
     ----------
@@ -428,6 +434,35 @@ def generate_archive(
         fh.write(result)
 
 
+def generate_archive(
+    articles: list[tuple[str, dict[str, Any]]],
+    template: Template,
+    output_dir: str,
+) -> None:
+    """Generate the archive page.
+
+    This is used for the full archive.
+
+    Parameters
+    ----------
+    articles
+        List of articles. Each article has the destination path and a
+        dictionary with the content.
+    template
+    output_dir
+
+    """
+    archive = []
+    for dst, context in articles:
+        entry = context.copy()
+        entry['dst'] = dst
+        archive.append(entry)
+
+    result = template.render(dict(archive=archive))
+    with open(f'{output_dir}/archive.html', 'w') as fh:
+        fh.write(result)
+
+
 def generate_tags(
     articles: list[tuple[str, dict[str, Any]]],
     tags_template: Template,

blag/templates/archive.html

@@ -1,6 +1,6 @@
 {% extends "base.html" %}
 
-{% block title %}{{ site.title }}{% endblock %}
+{% block title %}Archive{% endblock %}
 
 {% block content %}
 {% for entry in archive %}

blag/templates/base.html

@@ -20,6 +20,7 @@
         <h2>{{ site.description }}</h2>
         <ul>
           <li><a href="/">Blog</a></li>
+          <li><a href="/archive.html">Archive</a></li>
           <li><a href="/tags/">Tags</a></li>
           <li><a href="/atom.xml">Atom Feed</a></li>
         </ul>

blag/templates/index.html

@@ -0,0 +1,23 @@
+{% extends "base.html" %}
+
+{% block title %}{{ site.title }}{% endblock %}
+
+{% block content %}
+{% for entry in archive[:10] %}
+
+  {% if entry.title %}
+  <h1><a href="{{entry.dst}}">{{entry.title}}</a></h1>
+
+  {% if entry.description %}
+  <p>— {{ entry.description }}</p>
+  {% endif %}
+
+  {% endif %}
+
+  <p>Written on {{ entry.date.date() }}.</p>
+
+{% endfor %}
+
+<p><a href="/archive.html">all articles...</a></p>
+
+{% endblock %}

docs/blag.rst

@@ -195,7 +195,8 @@ Template     Used For                               Variables
 ============ ====================================== ===================
 page.html    pages (i.e. non-articles)              site, content, meta
 article.html articles (i.e. blog posts)             site, content, meta
-archive.html archive- and landing page of the blog  site, archive
+index.html   landing page of the blog               site, archive
+archive.html archive page of the blog               site, archive
 tags.html    list of tags                           site, tags
 tag.html     archive of Articles with a certain tag site, archive, tag
 ============ ====================================== ===================

tests/conftest.py

@@ -33,6 +33,11 @@ def article_template(environment: Environment) -> Iterator[Template]:
     yield environment.get_template('article.html')
 
 
+@pytest.fixture
+def index_template(environment: Environment) -> Iterator[Template]:
+    yield environment.get_template('index.html')
+
+
 @pytest.fixture
 def archive_template(environment: Environment) -> Iterator[Template]:
     yield environment.get_template('archive.html')

tests/test_blag.py

@@ -291,8 +291,10 @@ foo bar
     assert os.path.exists(f'{args.output_dir}/testdir/test')
     # ... feed
     assert os.path.exists(f'{args.output_dir}/atom.xml')
-    # ... archive
+    # ... index
     assert os.path.exists(f'{args.output_dir}/index.html')
+    # ... archive
+    assert os.path.exists(f'{args.output_dir}/archive.html')
     # ... tags
     assert os.path.exists(f'{args.output_dir}/tags/index.html')
     assert os.path.exists(f'{args.output_dir}/tags/foo.html')

tests/test_templates.py

@@ -27,6 +27,26 @@ def test_article(article_template: Template) -> None:
     assert '1980-05-09' in result
 
 
+def test_index(index_template: Template) -> None:
+    entry = {
+        'title': 'this is a title',
+        'dst': 'https://example.com/link',
+        'date': datetime.datetime(1980, 5, 9),
+    }
+    archive = [entry]
+    ctx = {
+        'archive': archive,
+    }
+    result = index_template.render(ctx)
+    assert 'site title' in result
+
+    assert 'this is a title' in result
+    assert '1980-05-09' in result
+    assert 'https://example.com/link' in result
+
+    assert '/archive.html' in result
+
+
 def test_archive(archive_template: Template) -> None:
     entry = {
         'title': 'this is a title',
@@ -38,7 +58,7 @@ def test_archive(archive_template: Template) -> None:
         'archive': archive,
     }
     result = archive_template.render(ctx)
-    assert 'site title' in result
+    assert 'Archive' in result
 
     assert 'this is a title' in result
     assert '1980-05-09' in result