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
perl --version
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
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
).
(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.
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.
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.)
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...
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.
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 on
index.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
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/
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.