Installing Frogdown on a Raspberry Pi

A Raspberry Pi is handy if you want to use Frogdown to see how it works. Or for testing out new web sites before you make them live on a real server.

Important note about the Raspberry Pi shortage

Create a Raspberry Pi boot SD and configure it for running Frogdown

Frogdown will run on any Raspberry Pi. If you are starting out with a new Raspberry Pi, here is how to create and configure a boot SD that works.

The assumption from here on out is that you are running from a command line.

SSH terminal with PuTTY and WinSCP for copying files

Use PuTTY for getting a terminal window from your Windows machine and use WinCSP for copying files between your local machine and your Raspberry Pi

Perl (and needed CPAN modules)

Frogdown is written in Perl. Perl is probably already installed. Check by typing

perl --version

But you will probably need to install some Perl modules from CPAN

ImageMagick is needed by Frogdown to deal with images

Frogdown needs ImageMagick to convert image files.

sudo apt update
sudo apt install imagemagick

Setting Environment variables

Edit ~/.bashrc (nano ~/.bashrc) and copy this

# Frogdown starts here

# alias is so you can process a single file like 'fd index.md frog`
alias fd='RunFrogdown.sh '

# So Frogdown can find /etc/markcms config files
export FHOME=$HOME/Frogdown

# Add the Frogdown bin directory to the existing path.
export PATH=$PATH:$HOME/Frogdown/bin

# Set PERL5LIB so that Frogdown can find the Frogdown Perl modules.
export PERL5LIB=$HOME/Frogdown/bin/perl5lib

# Create new custom commands for changing into directories
# we always need to change to whenever we log in.

# Change to the directory where we edit Frogdown .md files
cdfa ()
{
    cd "/home/pi/Frogdown/frog_authoring/Frogdown"
}

# Change to the directory where the .html files are written
cdfh ()
{
    # If you are using Apache2's default DocumentRoot
    #cd "/var/www/html/Frogdown"
    # If you haven't installed a web server.
    # Or have changed the web server's DocumentRoot
    cd "/home/pi/html/frog_html/Frogdown"
}

to the end of .bashrc. Save it (Ctl-o).

Resolving a chicken and egg problem

(There is a chicken-egg problem here. You need to have downloaded and unzipped Frogdown.zip before you can run TestPerl.pl. To unravel the time twist, go to the download-and-unzip section. Once you have Frogdown downloaded and unzipped, come back here to test.

Log in again in a different session before closing .bashrc. Type TestPerl.pl. It should run if the path variable was updated to include ~/Frogdown/bin (echo $PATH to see the PATH variable.) If TestPerl runs, it should display

TestPerl.pl  1.02  2022-04-11
Tests to see if you are set up to process Frogscript with MarkdownWrapper.pl
'FHOME' is used in place of 'HOME'

This is good:
  Module 'FrogUtils::utility' is loaded.
  Module 'FrogUtils::MarkdownW.pm' is loaded.
  Module 'FrogUtils::SmartyPantsW' is loaded.
  Module 'File::Path' is loaded.
  Module 'Digest::MD5' is loaded.
  Module 'Date::Calc' is loaded.

  Your HOME directory is '/home/pi/Frogdown/'
  Your configuration directory (/home/pi/Frogdown/etc/markcms/) exists.
  'frog.cfg' exists in your configuration directory.
  'frog-site.cfg' exists in your configuration directory.

Testing to see if ImageMagick is installed
Good! ImageMagick (convert) is installed. Which is close enough.

The FrogUtils modules are the ones we supply. The rest of the modules are from CPAN and may need to be installed if TestPerl.pl complains.

Downloading and unzipping Frogdown

If you have followed all my instructions on setting Apache's (or whatever web server) DocumentRoot, then you can use this 3 second install. Download it and save it as GetFrogdown.sh and put it in your ~ (home) directory (i.e., /home/pi). chmod +x GetFrogdown.sh to make it executable.

And then jump to checking the configuration files

However if you aren't using all my defaults (for setting up Apache, etc.), then it is better to install a step at a time.

Download Frogdown.zip into your home directory ~ (/home/pi usually).

cd ~
wget "http://www.frogymandias.org/Frogdown/Frogdown.zip"
unzip -q Frogdown.zip

Do some initial configuration

cd Frogdown/etc/markcms-linux-raspberry-pi
chmod 744 first-time.sh
./first-time.sh
cd ../markcms

first-time.sh Makes all the .sh and .pl files be executable (they aren't after being unzipped). Then it copies the configuration files from Frogdown/etc/markcms-linux-raspberry-pi to Frogdown/etc/markcms. You should then cd ../markcms so you can edit the configuration files.

You only run first-time.sh the first time you download and install Frogdown. If you update to a new version by downloading and unzipping Frogdown, do not run first-time.sh again. Because it will overwrite your configuration files in ~/etc/Frogdown/etc/markcms

At this point it is probably best to open another ssh terminal so you can edit the config files in markcms while running scripts and such in the other terminal window.

Configuration files

Edit ~/Frogdown/etc/markcms/frog-site.cfg There are two variables that need to be checked

# .md files you edit are here
BaseInDir = ~/Frogdown/frog_authoring

# The converted .html files will be written here
# Assuming that you changed Apache2's DocumentRoot
# (Or haven't installed any web server)
BaseOutDir = ~/Frogdown/frog_html
# Apache default (which is owned by root.  chown -R...)
#BaseOutDir = /var/www/html

If you already have a web server running and its DocumentRoot points to a different directory, then change BaseOutDir to be the same directory. i.e., where the .html files are to be written.

If you don't have a web server installed then leave BaseOutDir = ~/Frogdown/frog_html

~/Frogdown/etc/markcms/frog.cfg has variables that describe various defaults. You don't need to editing anything here now. Wait until you are more familiar with Frogdown and then come back to frog.cfg.

frog-site-locations.cfg isn't used yet. It is there for some future use.

(If this is the first time you installed Frogdown on this machine, go back to the chicken-egg part to run some tests. Then come back here when all the tests have passed.)

Running Frogdown in debug mode to test first

cd ~/Frogdown/frog-authoring/Frogdown, (cdfa if you added the _.bashrc_ functions.) if needed then

RunFrogdown.sh index.md debug | less

This tells MarkdownWrapper.pl, which is the Frogdown converter to process index.html, but with the 'debug' option. With debug, it won't generate a .html file. Instead, it will display a lot of configuration information and then stop. You should see something like

(snip...)

BaseInDir:         '/home/pi/Frogdown/frog_authoring/'
BaseOutDir:        '/home/pi/Frogdown/frog_html/'
InDir:             '/home/pi/Frogdown/frog_authoring/Frogdown/
OutDir:            '/home/pi/Frogdown/frog_html/Frogdown/
FilestoBeCopied:   'frog.csst'

InDir and Outdir should correspond to the variables you set in frog-site.cfg If this is correct then...

Running Frogdown for real to generate your web site.

Type

RunFrogdown.sh index.md

Will run MarkdownWrapper.pl. It will display a number of things, but the last line should be

Created HTML file: /home/pi/Frogdown/frog_html/Frogdown/index.html

Find the IP address of your Pi (hostname -I) and put that IP in your browser's URL bar. Add /Frogdown after the URL (the IP) and press enter. You should see the Frogdown page, that should look just like http://www.frogymandias.org/Frogdown/ (plus or minus a few changes.) At this point the rest of the pages won't exist, so clicking on the links at the bottom of the page will give a "404 File not found" error. So let's fix this and generate the rest of the pages. Type

./DoAllFrogs.sh

Which will generate GenAll.sh which is a script that will run Frogdown (MarkdownWrapper.pl) on all the .md files in the current directory. (Run ./GenAll.sh) Now you can click on the links at the bottom of the index page and pages should exist. You can go to ~/Frogdown/frog_html/Frogdown (or wherever OutDir is) and examine the .html files (and image files) that were just created.

If so, then congratulations! You now have a working Frogdown running on your Pi. See DogFood.html for instructions on the Frogdown markup language. (DogFood.text for the Frogdown source code for that page.)

You can now use Frogdown to create your own web pages. Make sure to copy DoAllFrogs.sh and frog.csst to any directory you will be working in. Look at the .md files in the Frogdown directory as example. Whenever I start a new page, I copy the configuration variables at the top of an existing .md file to a new file and then start writing text formated with Frogdown markup.

Optional: install Apache (and PHP)

A note about web servers

If you don't install a web server, you can see how the generated .html files look by navigating to the directory where the .html files are (default of ~/Frogdown/frog_html) and double clicking onindex.html` If you have a Samba share working on your ~ directory, you can navigate there from your Windows machine.

Or you might went to install the Apache web server which might not be installed on a fresh Raspberry Pi. Then you can access your .html files from any machine on your subnet. (The IP of your Raspberry Pi is the URL.) To install Apache (and php):

Final hints:

Because I usually only am editing one or two files at a time I make a copy of GenAll.sh and modify it to only process the files I am editing.

cp -p GenAll.sh GenOne
nano GenOne

and put "#" at the beginning of the lines you aren't currently editing.

And/or rename ~/Frogdown/bin/RunFrogdown.sh to have a shorter name. Or add an alias to ~./bashrc like

alias fd='RunFrogdown.sh '

log in again, change to the directory that contains your .md files and you can type (for example) fd index.md to convert index.md to index.html. You are generally only working on one or two pages in the same session and fd index.md (etc.) is easy to type. This is (roughly) how I've created all the pages on http://www.frogymandias.org/

Uh oh, it doesn't work!

If things aren't working correctly, run RunFrogdown.sh index.md debug | less again and examine the the variables closely.

Look at InDir and OutDir especially. Look through the configuration files in ~/Frogdown/etc/markcms. And/or double check the changes to .bashrc And/or any of the above instructions.