Papaya

A clean Zola theme for blogging and projects, forked from Anpu.

Demo site: https://justintennant.me/papaya/

index

projects

project

Features

Installation

  1. Clone this repository to your themes folder:

    git clone https://github.com/justint/papaya.git themes/papaya
    
  2. Set your theme setting in config.toml to papaya:

    theme = "papaya"
    
  3. This theme requires both the tags and categories taxonomies.

    taxonomies = [
        { name = "categories" },
        { name = "tags" },
    ]
    
  4. In your content directory, add new blog and projects directories. Copy the _index.md file from Papaya's content/blog into your content/blog, and the _index.md and categories.json files from Papaya's content/projects into your content/projects.

    Your content directory structure should look like this:

    content
    β”œβ”€β”€ blog
    β”‚  └── _index.md
    └── projects
       └── _index.md
       └── categories.json
    
  5. (optional) To enable GitHub repository stars/fork counts (disabled by default to avoid hitting API rate limits), set the $ZOLA_ENV environment variable to prod prior to your zola serve/zola build execution.

    For csh/tsch:

    setenv ZOLA_ENV prod
    

    For bash/ksh/zsh:

    export ZOLA_ENV=prod
    

Customization

Here are the customizable features of Papaya:

In your config.toml under the [extra] section you need to set the papaya_menu_links list.

Example:

[extra]
papaya_menu_links = [
    { url = "$BASE_URL/about/", name = "About" },
]

If you include $BASE_URL in the URL of a link it will be replaced with the base URL of your site.

Post/project date formats

In your config.toml under the [extra] section you need to set the papaya_date_format value.

Example:

[extra]
papaya_date_format = "%e %B %Y"

The formatting uses the standard date filter in Tera. The date format options you can use are listed in the chrono crate documentation.

Post/project featured images

Posts and projects can have featured images which display at the top of their page before the page contents.

[extra]
featured_image = "image.jpg"
featured_image_alt = "A lodge overlooks a forested mountain range."

Featured image

Featured images can also be extended to the full width of the viewport:

[extra]
featured_image = "image.jpg"
featured_image_alt = "A lodge overlooks a forested mountain range."
featured_image_extended = true

Featured image, extended

Project categories

In your content/projects/categories.json, you can specify the categories of projects. The formatting of the file is:

{
   "title": "keyword"
}

A project can have multiple categories, and will be displayed once in each category configured.

Projects without categories will be displayed in the "Other" category listing of your project page. If you don't want the "Other" category displayed, you can copy the templates/projects.html to your own templates directory and delete/comment out the "Other" category code.

Example categories.json:

{
  "Software": "software",
  "Films": "film"
}

Example project page front matter:

title = "Example software project"
date = 2021-08-11

[taxonomies]
categories = ["software"]

The example project page above would be grouped into & displayed within the "Software" category of your projects page.

Open Graph Protocol locale/profile information

In your config.toml you can add a [extra.ogp] section to specify your Open Graph Protocol locale and profile information.

Open Graph Protocol provides you control over how your website's content should be displayed on social media sites.

For the more information on Open Graph Protocol and valid property values, visit the official website.

Example:

[extra.ogp]
locale = "en_US"
first_name = "Papaya"
last_name = "Tiliqua"
gender = "female"
username = "tiliquasp"

In your config.toml you can add a [extra.social] section to specify your social network/contact accounts. Changing these will update what links appear on your website's footer.

Example:

[extra.social]
email = "papaya@tiliqua.sp"
github = "papaya"
linkedin = "papayatiliqua"

Image embedding shortcode

Included with Papaya is a shortcode for embedding images into your posts:

img(path, alt, caption, class, extended_width_pct)

Arguments

The benefits of using this shortcode over regular Markdown/HTML image embedding are:

Extended width images

Images embedded into pages using the img shortcode can be configured to extend past their document width. This is especially nice for displaying wide/landscape images at higher resolutions.

By default, images embedded with the img shortcode will be inserted as a figure with default margins:

{{ img(path="image.jpg", 
       alt="A very cute leopard gecko.", 
       caption="A very cute leopard gecko. Default sizing.") }}

Default sized image

With the extended_width_pct argument, we can specify a percentage of how much the image should expand outside its default figure width, up to your maximum configured image width (config.extras.images.max_width, 2500px default).

Here's an example with extended_width_pct=0.1:

{{ img(path="image.jpg", 
       alt="A very cute leopard gecko.", 
       caption="A very cute leopard gecko. extended_width_pct=0.1",
       extended_width_pct=0.1) }}

Image extended by 0.1

The image is now displayed with a 10% larger width, while maintaining its original aspect ratio.

Here's an even wider example:

{{ img(path="image.jpg", 
       alt="A very cute leopard gecko.", 
       caption="A very cute leopard gecko. extended_width_pct=0.2",
       extended_width_pct=0.2) }}

Image extended by 0.2

The images will resize in resolution up to your maximum configured image width, and will display on the webpage up to the maximum width of the viewport.

You can also force the image width to match the document's width by setting extended_width_pct to -1:

{{ img(path="image.jpg", 
       alt="A very cute leopard gecko.", 
       caption="A very cute leopard gecko. extended_width_pct=-1",
       extended_width_pct=-1) }}

Image fixed to document width

Why "Papaya"?

🦎