Start your own blog/site with Podlite for Web

Recently I released the tool Podlite for Web which helps to create websites and blogs using the markup language Raku Pod (also known as pod6). It replaces my previous engine based on gatsby.

I want to give you little tips to help you create your own website/blog.

Installation

For startup you need yarn should be installed. Podlite-web is also available as Docker image.

First you checkout the repo and start the development server:

git clone git@github.com:podlite/podlite-web.git 
cd podlite-web
yarn && yarn dev

And after open URL: http://localhost:3000/

This is the default page. The sources of this page are available in the pub directory. You can edit the file pub/index.pod6 and see the changes.

Blog example

You can also explore the examples directory and check use cases.

The most useful example is examples/03-blog.

Run blog example

To play with it, add the variable POSTS_PATH:

POSTS_PATH='examples/03-blog' yarn dev

or using docker:

cd examples/03-blog
docker run -it --rm -v ${PWD}:/app/pub -p 3000:3000 podlite/podlite-web dev

And then open the URL: http://localhost:3000/

Files structure

Let's look at this in detail.

examples/03-blog contains the following files:

├── about.pod6     # static /about page
├── blog-post.pod6 # example of a blog post
├── content.pod6   # /contents page with TOC for blog at all
├── index.pod6     # this is an index file of the website
├── journal.pod6   # file with selectively published notes 
├── logo.png       # image used for :favicon and in =Image block
├── now.pod6       # static /now page
└── styles.css     # css for custom styles 

Index page

The file index.pod6 is the same as the file index.html for a normal website. This is the root file for the website and also the configuration for the website in general.

Let's see the =pod section from the example for this:

=begin pod  = :favicon<./logo.png> 
= :puburl<http://example.com> 
= :globalStyles("./styles.css")  
=TITLE Podlite-web Starter Blog  ... 
=end pod

The following configuration options for the =pod block are used :

Site configuration attributes

The semantic block '=TITLE' is used as the site title.

Create static pages

Each static page has a fixed URL. This is possible with the :puburl attribute for the =pod block. For example, let's look at about.pod6:

=begin pod :pubdate('2022-08-08 23:00:00') :puburl</about>
=TITLE About page
=end pod

with pubdate - is needed to indicate that this page is publicly available from a certain date. Pages without pubdate will be skipped when published.

Blog posts

Pages without puburl are treated as blog posts and the URL is generated based on the publication date.

For example:

=begin pod :pubdate('2012-08-08 23:00:00')
=TITLE Blog post  
=end pod

will be available at url /2022/8/6/1/blog-post.

The =TITLE block is used for the public URL and as the page title.

Publish notes

It is also possible to create a blog note from any =para block. Let's look at the file journal.pod6.

=begin pod  
=TITLE This is a journal  

I write down my thoughts here, but I only want to share a few  

=for para :pubdate('2022-07-04 14:00')
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem
Ipsum has been the industry's standard dummy text ever 
since the 1500s, ...

=for para :pubdate('2022-08-05 14:00')
It is a long
established fact that a reader will be distracted by the
readable content of a page when looking at its layout.

....

As you can see, journal.pod6 can be a diary, some entries of which can be published in a blog. But journal.pod6 remains unpublished: there is no attribute pubdate in =pod section.

Other features

Linking pages

Let's first create a link to the info page. For this we use the L<> formatting code:

Please check L<About page|file:./about.pod6>

This link between files becomes a web link on the website. Links to files are converted to links between web pages when they are published.

It be rendered as:

<a href="/about">About</a>

Link to file with blog post:

This is a link to L<blog-post.pod6| B<file:./blog-post.pod6>>

converted to :

<p>This is a link to <a href="/2022/8/6/2/blog-post">blog-post.pod6</a></p>

React support

It is possible to integrate Pod with React components. We'll show you how to add the Contents of blog component to the page:

# Here we import the component _Contents_ from the library 
=useReact  {Contents} from '@Components/service' 
# Somewhere on the page run this component with parameters 
=begin React :component<Contents> :locale<en>
=end React

The content of the blog is rendered as follows:

All Pod blocks are passed as childs to the React component. It is possible to mix the pod markup with the logic.

For example, to create a multi-column layout, you pass each column as a Pod block to the React component. The following example shows the site menu:

=useReact {HeaderCol} from '@Components/service'
=begin React :component<HeaderCol> :id<menu>  
=para L<About|file:./about.pod6> 
=para L<Now|file:./now.pod6> 
=para L<Table of contents|file:./content.pod6> 
=para L<github | https://github.com/podlite> 
=para L<twitter | https://twitter.com> 
=end React

It showing on the following screen:

RSS, Sitemap

Rss feed and sitemap are generated automatically.

Publish results

Podlite-web make zipped archive of result by the following command:

yarn export-zip > file.zip

You can unzip the file and transfer the contents to almost any hosting provider to make your website live.

Usage of Podlite for Web

Useful links

• Pod6 - An easy-to-use markup language for documenting Raku modules and programs

• Specification of pod6: Synopsis 26

• Online editor: https://pod6.in

• Podlite - open-source desktop pod6 editor for Windows, Linux, and Mac.

I look forward to your feedback on the Podlite GitHub issue page . Or just write me to zag(at)cpan.org with your ideas!

Thank you!