mkwebpage

description :

mkwebpage is a POSIX sh script used to convert a markdown file to a valid html file. It offers various options to customize your webpage (title, keywords, icons, css etc)

it relies heavily on pandoc and tidy so you must install them on your system.

the goal here is to make this script as self-contained as possible, portable between linux and BSD and to be able to easily generate webpages in batches.

---

how to use :

add this script to /usr/local/bin/ (or anywhere in your $PATH) and make it belong to your user and executable with chown myuser /usr/local/bin/mkwebpage;chmod u+x /usr/local/bin/mkwebpage

$ mkwebpage -h


usage:

        mkwebpage [optional options] -f filetoconvert.md

        -b      create a back button in the html body
        -f      the markdown file you want to convert to a webpage
        -c      path to the css file you want for this site
        -h      print help
        -i      path to the .ico file you want for this site
        -k      keywords you want to use for this site
        -l      language attribute for this page
        -s      use a source file for some/all the optional options of this menu
        -t      title of this page
        -z      change the path of the back button

OPTIONS PRECEDENCE :

1. options passed via the command line have the highest precedence
2. next is the options passed via a source file
3. and last is the default options hardcoded in the script

---

examples :

for the examples, cd into examples

cd examples

create a single page passing all the options via cli:

mkwebpage -b -z "https://duckduckgo.com" -c "./my.css" -i "./my.ico" -t "Welcome to my webpage!" -k "linux geek BSD ksh" -l "en" -f myfile.md > mywebsite.html

ok, it works, but too long, not convenient.

In the above example, the -l option could have been ommited since LANGUAGE="en" is hardcoded as a default in the script.

A problem arise when you have multiples webpages that are not in a single folder (think nested directories). a group of pages in a given folder might want to common values such as keywords, css, icon etc.

this is where the -s options becomes handy; you can pass some or all of your arguments with it.

lets create a nested directory for the example

mkdir -p deeply/nested/directory/

and lets say all the pages there should share the same css, ico and back button location

we can create a source file for these pages

vim deeply_nested_source.mkwebpage

that will contain the path for : the css, the ico file and the path where the back button should bring you:

#LANGUAGE="en"
ICO="../../../my.ico"
CSS="../../../my.css"
#KEYWORDS="default keywords"
#TITLE="default title"
BACK_PATH="../../../mywebsite.html"

you can now create 2 additional pages that share the above properties with :

mkwebpage -b -s "./deeply_nested_source.mkwebpage" -t "subpage2" -k "kornshell" -f mysecondfile.md > deeply/nested/directory/subpage2.html

and

mkwebpage -b -s "./deeply_nested_source.mkwebpage" -t "subpage3" -k "linux" -f mythirdfile.md > deeply/nested/directory/subpage3.html

oh no, I want to change the .css on subpage3! No problem with option precedence

mkwebpage -b -s "./deeply_nested_source.mkwebpage" -c "../../../myother.css" -t "subpage3" -k "linux" -f mythirdfile.md > deeply/nested/directory/subpage3.html

okay, but you have 50 webpages to convert! No problem, you create a script that keeps track of the commands to generate the pages : (based on the 3 examples above)

vim mk_all_webpages.sh 

#!/usr/bin/env sh

mkwebpage -b -z "https://duckduckgo.com" -c "./my.css" -i "./my.ico" -t "Welcome to my webpage!" -k "linux geek BSD ksh" -l "en" -f myfile.md > mywebsite.html
mkwebpage -b -s "./deeply_nested_source.mkwebpage" -t "subpage2" -k "kornshell" -f mysecondfile.md > deeply/nested/directory/subpage2.html
mkwebpage -b -s "./deeply_nested_source.mkwebpage" -c "../../../myother.css" -t "subpage3" -k "linux" -f mythirdfile.md > deeply/nested/directory/subpage3.html

now, you can backup your whole website by saving :

• the script above
• your directory structure (can be included in the script)
• your .md files
• your .mkwebpage files.

and when you need to modify a page, you just change the markdown files and re-run ./mk_all_webpages.sh (chmod and chown the script accordingly).

---

Closing notes

• in the examples, I put the .md files and the .mkwebpage source files at the root of the example folder
  • this looks a bit messy, you can design your directory structure and files placement in a more relevant way that fit your needs.
• some options in this script seems to be already covered in pandoc. I tend to re-invent the wheel often.
  • i may offload some option to pandoc in the future, but for now, this fits my use case with the help menu and the easy modularity.

*** - this repository is mirrored from gitea ***