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.
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.
Frogdown is written in Perl. Perl is probably already installed. Check by typing
But you will probably need to install some Perl modules from CPAN
Frogdown needs ImageMagick to convert image files.
sudo apt update
sudo apt install imagemagick
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
# Add the Frogdown bin directory to the existing path.
# Set PERL5LIB so that Frogdown can find the Frogdown Perl modules.
# 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
# Change to the directory where the .html files are written
# If you are using Apache2's default DocumentRoot
# If you haven't installed a web server.
# Or have changed the web server's DocumentRoot
to the end of
.bashrc. Save it (
(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
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.
FrogUtils modules are the ones we supply. The rest of the modules are from CPAN and may need to be installed if
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.,
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 ~ (
unzip -q Frogdown.zip
Do some initial configuration
chmod 744 first-time.sh
first-time.sh Makes all the
.pl files be executable (they aren't after being unzipped). Then it copies the configuration files from
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
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.
~/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-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.)
cd ~/Frogdown/frog-authoring/Frogdown, (
cdfa if you added the _.bashrc_ functions.) if needed then
RunFrogdown.sh index.md debug | less
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
Outdir should correspond to the variables you set in
frog-site.cfg If this is correct then...
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
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
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.
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):
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
and put "#" at the beginning of the lines you aren't currently editing.
~/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.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/
If things aren't working correctly, run
RunFrogdown.sh index.md debug | less again and examine the the variables closely.
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.