NAME

Dancer2::Plugin::LiteBlog::Article - Represents a single article or page in LiteBlog.

SYNOPSIS

    use Dancer2::Plugin::LiteBlog::Article;

    my $article = Dancer2::Plugin::LiteBlog::Article->new(
        basedir => '/path/to/article/directory'
    );

    print $article->title;
    print $article->published_date;
    print $article->content;

DESCRIPTION

This module provides an object-oriented interface to manage individual articles or pages for LiteBlog, a Dancer2-based blogging platform. Each article contains metadata and content, parsed from two specific files located in the directory root of the Article: meta.yml and content.md.

METHODS

BUILD

At build time, this class validates the integrity of the Article. Namely, it makes sure the object is corretly initialized, which means a valid meta.yml and contend.md files are found and successfully parsed in the basedir.

ATTRIBUTES

basedir

The base directory where the article files (content.md, meta.yml) reside. Note that the directory name is used as the slug of the article. Must be an existing directory, read-only and required attribute.

    my $basedir = $article->basedir;

base_path

The base path for articles, when constructing URLs for the articles. Defaults to '/blog'.

slug

Derived from the article directory's name, representing the URL-friendly version of the title.

category

Articles directly under the 'articles' directory are considered 'page'. Articles that are stored in a sub-directory, below the articles directory are considered articles of that category.

Examples:

    .../articles/some-page # this is a page (top-level article)
    .../articles/tech/a-blog-post # this is a blog post under the 'tech' category.

Note: this will be changed in future version, the hard-coded value 'articles' will become an attribute of this class so that it can be changed (parent_directory).

is_page

Boolean indicating whether the article is a standalone page, based on the value returned by category.

published_time

The time the article was published, derived from the content file's modification time.

published_date

Formatted publishing date, e.g., "25 October, 2023", derived from published_time.

meta

A hash reference containing metadata of the article loaded from the 'meta.yml' file. That file is supposed to be located within the directory of the Article (basedir).

title

The title of the article. Parsed from the content of meta.yml.

image

An associated image for the article, if any.

Parsed from the content of meta.yml. If that value is relative (no starting '/'), then it is transformed into the absolute permalink of the asset, using base_path, the category if needed and the slug.

If the image meta field is an absolute path (either starting with a / or with https?, it is returned unchanged.

Example:

    image: "featured.jpg" # in article/meta.yml
    $article->image; # returns '/blog/cat/some-article/featured.jpg' 

background

If defined in meta.yml, this is expected to be a path to a big image that will be used as the background image of the whole page. As with image, if the path is relative, it will be transformed to its absolute form, based on the Article location.

author

The author of the article/page. To be displayed in the meta data of the HTML.

tags

Array reference of tags associated with the article. Parsed from the content of meta.yml.

excerpt

A brief summary or excerpt of the article. Parsed from the content of meta.yml.

The article's unique URL path. Derived from base_path, category and slug.

content

The content of the article, parsed from the associated Markdown file content.md and rendered to HTML. That file is supposed to be located in the basedir of the Article.

SEE ALSO

Dancer2::Plugin::LiteBlog, Text::Markdown

AUTHOR

Alexis Sukrieh, <sukria@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2023 by Alexis Sukrieh.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.