NAME

Giblog - Create Websites and Blogs that can be managed with Git

Website

Blog

DESCRIPTION

Giblog is a utility to create websites or blogs. You can create websites or blogs using giblog command. All created files is static files. You can manage them using git. You can customize websites using Perl.

SYNOPSYS

  # New empty website
  $ giblog new mysite

  # New website
  $ giblog new_website mysite

  # New blog
  $ giblog new_blog mysite

  # Change directory
  $ cd mysite

  # Add new entry
  $ giblog add

  # Add new entry with home directory
  $ giblog add -C /home/perlclub/mysite

  # Build website
  $ giblog build
  
  # Build website with home directory
  $ giblog build -C /home/perlclub/mysite

  # Serve a website
  $ giblog serve

  # Save a website
  $ giblog save -m "Commit Messages" origin main

  # Publish website
  $ giblog publish origin main

  # Deploy a website
  $ giblog deploy
  
  # Do "giblog build", "giblog save", "giblog publish", "giblog deploy" at once
  $ giblog all -m "Commit Messages" origin main

FEATURES

Giblog have the following features.

Build websites and blogs.
All created files is static files. You can manage files using git.
Linux, macOS, Windows Support. (Windows needs msys2 or WSL2)
CSS supports smart phone.
Header, hooter and side bar support
Customize top and bottom section of content.
Customize HTML head.
Automatical Line break. p tag is automatically added.
Escape <, > automatically in pre tag
Title tag is automatically added from first h1-h6 tag.
Description meta tag is automatically added from first p tag.
You can customize your website by Perl.
You can serve your website in local environment. Contents changes is detected and build automatically(need Mojolicious).
Fast. Build 645 pages by 0.78 seconds in starndard linux environment.
Support Github Pages, both user and project page.

TUTORIAL

Create Websites

Create a Empty website

giblog new command create empty website. "mysite" is a name of your website.

  giblog new mysite

If you want to create empty site, choice this command. Templates and CSS is empty and provide minimal site building process.

Create a Website

giblog new_website command create simple website. "mysite" is a name of your website.

  giblog new_website mysite

If you want to create simple website, choice this command. Top page "templates/index.html" is created. List page "templates/list.html" is created, which is prepare to create blog entry pages easily for feature.

CSS is responsive design and supports smart phone and provide basic site building process.

Create a Blog

giblog new_blog command create empty website. "mysite" is a name of your website.

  giblog new_blog mysite

If you want to create blog, choice this prototype. Top page "templates/index.html" is created, which show 7 days entries. List page "templates/list.html" is created, which show all entries links.

CSS is responsive design and supports smart phone and provide basic blog building process.

Add a Blog Page

giblog add command add entry page.

  giblog add

You need to change the directory created by giblog new, giblog new_website, or giblog new_blog before

Created file name is, for example,

  templates/blog/20080108132865.html

This file name contains current date and time.

To write new entry, You open it, write h2 head and content.

  <h2>How to use Giblog</h2>

  How to use Giblog. This is ...

Other parts wrapping content like Header and footer is automatically added in building process.

Add a Content Page

If you want to create content page, put file into "templates" directory.

  templates/access.html
  templates/profile.html

Then open these file, write h2 head and content.

  <h2>How to use Giblog</h2>

  How to use Giblog. This is ...

Other parts wrapping content like Header and footer is automatically added in building process.

You can put file into sub directory.

  templates/profile/more.html

Note that "templates/static" and "templates/common" is special directories. Don't push content page files into these directories.

  # Special directories you don't put content page files into
  templates/static
  templates/common

Add Satic files

If you want to add static files like css, images, JavaScript, You put these file into "templates/static" directory.

Files in "templates/static" directory is only copied to public files by build process.

  templates/static/js/jquery.js
  templates/static/images/logo.png
  templates/static/css/more.css

Customize Header or Footer, Side bar, Top of Content, Bottom of Content

You can customize header, footer, side bar, top of content, bottom of content.

  ------------------------
  Header
  ------------------------
  Top of content   |
  -----------------|
                   |Side
  Content          |bar
                   |
  -----------------|
  Bottom of content|
  ------------------------
  Footer
  ------------------------

If you want to edit these section, you edit these files.

  templates/common/header.html     Header
  templates/common/top.html        Top of content
  templates/common/side.html       Side bar
  templates/common/bottom.html     Bottom of content
  templates/common/footer.html     Footer

Customize HTML Header

You can customize HTML header.

  <html>
    <head>
      <!-- HTML header -->
    </head>
    <body>

    </body>
  </html>

If you want to edit HTML header, you edit the following file.

  templates/common/meta.html

Giblog Variables

Explains Giblog variables.

Define Giblog Variables

You can define Giblog variable in giblog.conf.

  # giblog.conf
  use strict;
  use warnings;
  use utf8;

  {
    site_title => 'mysite',
    site_url => 'http://somesite.example',
    
    # Variables
    vars => {
      giblog_test_variable => 'Giblog Test Variable',
    },
  }

vars defines Giblog variables in giblog.conf.

Use Giblog Variables

Use Giblog variables in templtes files.

  <%= $GIBLOG_VARIABLE_NAME %>

Examples:

giblog.conf

  # giblog.conf
  use strict;
  use warnings;
  use utf8;

  {
    site_title => 'mysite',
    site_url => 'http://somesite.example',
    
    # Variables
    vars => {
      giblog_test_variable => 'Giblog Test Variable',
      google_analytics_id => 'G-EIFHDUGHF45',
    },
  }

templates/common/meta.html

  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width,initial-scale=1.0,minimum-scale=1.0">
  <link rel="shortcut icon" href="/images/logo.png">

  <!-- Global site tag (gtag.js) - Google Analytics -->
  <script async src="https://www.googletagmanager.com/gtag/js?id=<%= $google_analytics_id %>"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());

    gtag('config', '<%= $google_analytics_id %>');
  </script>

Build a Website

Build a website using giblog build command.

  giblog build

You need to change the directory created by giblog new, giblog new_website, or giblog new_blog before executing "giblog build" command.

giblog build command execute run method of Giblog::Command::build module.

Giblog::Command::build module exists in lib/Giblog/Command/build.pm.

Giblog::Command::build module is automatically created.

See Giblog::Command::build module.

  # "lib/Giblog/Command/build.pm" in website created by "new_blog" command
  package Giblog::Command::build;

  use base 'Giblog::Command';

  use strict;
  use warnings;

  use File::Basename 'basename';

  sub run {
    my ($self, @args) = @_;

    # API
    my $api = $self->api;

    # Read config
    my $config = $api->read_config;

    # Copy static files to public
    $api->copy_static_files_to_public;

    # Get files in templates directory
    my $files = $api->get_templates_files;

    # Add base path to public css files
    $api->add_base_path_to_public_css_files;

    for my $file (@$files) {
      # Data
      my $data = {file => $file};

      # Get content from file in templates directory
      $api->get_content($data);

      # Parse Giblog syntax
      $api->parse_giblog_syntax($data);

      # Parse title
      $api->parse_title_from_first_h_tag($data);

      # Edit title
      my $site_title = $config->{site_title};
      if ($data->{file} eq 'index.html' || !defined $data->{title}) {
        $data->{title} = $site_title;
      }
      else {
        $data->{title} = "$data->{title} - $site_title";
      }

      # Add page link
      $api->add_page_link_to_first_h_tag($data, {root => 'index.html'});

      # Parse description
      $api->parse_description_from_first_p_tag($data);

      # Read common templates
      $api->read_common_templates($data);

      # Add meta title
      $api->add_meta_title($data);

      # Add meta description
      $api->add_meta_description($data);

      # Build entry html
      $api->build_entry($data);

      # Build whole html
      $api->build_html($data);

      # Replace Giblog variables
      $api->replace_vars($data);
      
      # Add base path to content
      $api->add_base_path_to_content($data);

      # Write to public file
      $api->write_to_public_file($data);
    }

    # Create index page
    $self->create_index;

    # Create list page
    $self->create_list;
  }

You can customize build process using Giblog::API and any Perl programs.

Giblog::API is a usuful APIs to customize websites.

Serve a Website

You can serve a website by giblog serve command.

   # Serve website
   giblog serve

You see the following message.

   Web application available at http://127.0.0.1:3000

giblog serve means the following command. morbo is a command to serve a Mojolicious app in development mode.

   # Same as the following
   morbo -w giblog.conf -w lib -w templates serve.pl

If giblog.conf, files in templates or lib directories are changed, the website is automatically rebuild.

Giblog 1.0:

If you use Giblog 1, you can serve your website by the following way.

   # Giblog 1.0
   morbo -w giblog.conf -w lib -w templates serve.pl

Save a Website

Save Websites using giblog save.

  giblog save -m "Commit Messages" origin main

giblog save means the following git commands.

  git add --all
  git commit -m "Commit Messages"
  git push origin main

Publish a Website

Publish the website using giblog publish command.

   # Publish the website
   giblog publish origin main

This is the same as the following command. In this example, the repository name is origin and the branch name is main. YY-mm-dd HH:MM:SS is current date and time.

  git -C public add --all
  git -C public commit -m "Published by Giblog at YY-mm-dd HH:MM:SS"
  git -C public push -f origin main

Deploy a Website

Deploy websites using giblog deploy.

  # Deploy websites
  giblog deploy

giblog save means the following command.

  perl deploy.pl

You can write any program for the deployment in deploy.pl.

  use strict;
  use warnings;

  my @args = @ARGV;

  my $deploy_cmd = q(ssh prod_perl_club_sites 'git -C ~/www/en_perlzemi-public fetch && git -C ~/www/en_perlzemi-public reset --hard origin/main');

  system($deploy_cmd) == 0
    or die "Can't execute deploy command: $deploy_cmd:$!";

Execute All Commands at Once

Do all Publish the website using giblog build, giblog save, giblog publish, giblog deploy command.

  giblog all -m "Commit Messages" origin main

This means the following commands

  giblog build
  giblog save -m "Hello" origin main
  giblog publish origin main
  giblog deploy

If --no-build option is specified, "giblog build" is not executed.

  giblog all --no-build -m "Commit Messages" origin main

If --no-save option is specified, "giblog save" is not executed.

  giblog all --no-save -m "Commit Messages" origin main

If --no-publish option is specified, "giblog publish" is not executed.

  giblog all --no-publish -m "Commit Messages" origin main

If --no-deploy option is specified, "giblog deploy" is not executed.

  giblog all --no-deploy -m "Commit Messages" origin main

CONFIG FILE

Giblog config file is "giblog.conf".

This is Perl script and return config as hash reference.

  use strict;
  use warnings;
  use utf8;

  # giblog.conf
  {
    site_title => 'mysite😄',
    site_url => 'http://somesite.example',
  }

site_title

  site_title => 'mysite😄'

Site title

site_url

  site_url => 'http://somesite.example'

Site URL.

base_path

  base_path => '/subdir'

Base path. Base path is used to deploy your site to sub directory.

For example, Project page URL of Github Pages is

  https://yuki-kimoto.github.io/giblog-theme1-public/

You specify the following

  base_path => '/giblog-theme1-public'

Top character of base_path must be slash "/".

HTML files is output into "public/giblog-theme1-public" directory.

METHODS

These methods is internally methods. Normally, you don't need to know these methods. See Giblog::API to manipulate HTML contents.

new

  my $api = Giblog->new(%params);

Create Giblog object.

Parameters:

home_dir - home directory
config - config

run_command

  $giblog->run_command(@argv);

Run command system.

config

  my $config = $giblog->config;

Get Giblog config.

home_dir

  my $home_dir = $giblog->home_dir;

Get home directory.

DOCUMENT

FAQ

Dose Giblog support Windows?

Giblog doesn't support native Windows(Strawberry Perl, or Active Perl) because Giblog depends on Git and Mojolicious.

If you use Giblog in Windows, you can use msys2 or WSL2.

What is the lowest version of Perl supported by Giblog?

The lowest version of Perl is the same version as Mojolicious because Giblog depends on Mojolicious. The current version is Perl 5.16+.

What is the lowest version of Git required by Giblog?

Git 1.8.5+.

What to consider when upgrading from Giblog 2 to Giblog 3?

Giblog 3.0 is compatible with Giblog 2.0. You can upgrade from Giblog 2.0 to Giblog 3.0 naturally.

What to consider when upgrading from Giblog 1 to Giblog 2?

From Giblog 2.0 the lowest version of Perl depends on Mojolicious, so use the latest Perl as possible.

Git 1.8.5+ is required.

OFFICEAL SITE

Giblog Official Site

AUTHOR

Yuki Kimoto, <kimoto.yuki at gmail.com>

CONTRIBUTORS

Yasuaki Omokawa, <omokawa at senk-inc.co.jp>

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

To install Giblog, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Giblog

CPAN shell

perl -MCPAN -e shell
install Giblog

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)