Building a website in Markdown with Pandoc
Styling with CSS
Styling should occur in a separate file, outside of the page. Any file you point to with the -H
option will be copied in, and that can include a CSS file as part of the final directory structure.
Usually, you will start by using an existing style. In this example, you can copy the Tufte CSS file into one of your sub-directories and add the link to a header file:
<link rel="stylesheet" href="Tufte/tufte.css"/>
Footer and Header
If you want your website to look tidy and professional, you might want the site name and URL to appear in a header or footer bar to let people know where they are regardless of which page they are on.
As mentioned previously, the options -B
(before the body) and -A
(after the body) let you create headers and footers. You could use these options to create a navigation bar at the top or a consistent footer for all pages. You can repeat these options as many times as you like, though the final result will suffer if you overdo things.
To create the header text you want, save the text in a file and specify the file name with the pandoc
command using the -B
option (Listing 2).
Listing 2
Specifying Headers and Footers
$ pandoc -t html\ -H head.html \ -s -o index.html \ -A footer.html \ -B toptext.html \ --metadata title="Kick Mundane Out" index.md \
Note that Listing 2 also brings in the CSS style sheet using the -H
parameter. In this case, the head.html
file only contains a link to the stylesheet.
Suppose I wish to add a copyright notice at the bottom. You can also imagine other things that might appear in a footer, such as social links and other legal information. The footer
id tag is common in CSS stylesheets (Listing 3).
Listing 3
footer.html Footer
footer.html <C> <div id="footer"> © 2021 Mats Tage Axelsson </div> <C>
A simple nav bar in the header could show the other pages on the site in a list (Listing 4).
Listing 4
toptext.html Header
<C> <div id="nav-bar"> <ul> <li>Home</li> <li>projects</li> <li>About</li> </ul> </div> <C>
Templates
When you convert to a new format, Pandoc will use a default template. Alternatively, you can create your own template. The easiest way to create a template is to write an existing template to your directory and edit it:
pandoc -D html > MyTemplate.tmpl
The simplest sites do not need templates. However, templates provide a means for incorporating variables and simple conditionals that add power and convenience to your web presence.
A template is a file in the final format that you seek – in this case, HTML files. The big difference between a template and an ordinary file is that templates have variables embedded. In short, variables are enclosed in dollar signs, and you assign values to those variables using your defaults file or command-line options.
For instance, you could use a metadata variable as a placeholder for a title. Then in the defaults file or as part of the pandoc
command, you could specify a title for the page:
--metadata title="Escape Mundane Life"
If the title shows up in the default template, it comes with conditions. Pandoc checks if title
is defined elsewhere, and if not, it puts it in (Listing 5).
Listing 5
Conditional Default Title
01 $if(title)$ 02 <header id="title-block-header"> 03 <h1 class="title">$title$</h1> 04 $if(subtitle)$ 05 <p class="subtitle">$subtitle$</p> 06 $endif$
As you can see, Listing 5 defines both the title and subtitle.
Some ready-made templates are available to help you add common features to your website. For instance, the pandoc-bootstrap
[3] template includes several elements that add value to your site. Bootstrap sets up CSS and connects to some JavaScript to give you a navigation bar and maybe a table of contents. You can also add an author name and a date.
In the code, you define where you want the variables to go:
$for(author-meta)$ <meta name="author" content="$author-meta$" /> $endfor$ $if(date-meta)$ <meta name="date" content="$date-meta$" /> $endif$
There are two ways of setting the values; one method is to add a YAML block [4] at the top of your document, in this case, index.md
.
The three dashes indicate the start and end of a block:
--- subtitle: "More creativity" author: "Mats Tage Axelsson" date: "2021-08-12" ---
The other way to set the variables is with the -V
parameter. For instance, note that the command in Listing 6 sets the date using the -V
variable.
Listing 6
Setting Variables with -V
pandoc index.md\ -o index.html\ -s\ -t html5+smart\ -V date="2021-08-15"\ -M subtitle="More Vitality"\ --template ../pandoc-bootstrap-adaptive-template/template.html\ -B toptext.html\ -A footer.html\ -c ../pandoc-bootstrap-adaptive-template/template.css\ --metadata title="Escape Mundane Life"
As you can see in Figure 2, the data is added to your web page.
« Previous 1 2 3 4 Next »
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Direct Download
Read full article as PDF:
Price $2.95
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Find SysAdmin Jobs
News
-
SparkyLinux 6.6 Now Available for Installation
The Debian-based SparkyLinux has a new point release that retools the live USB desktop creator and other changes that give it shiny new-ness.
-
SparkyLinux 6.6 Now Available for Installation
The Debian-based SparkyLinux has a new point release that retools the live USB desktop creator and other changes that give it shiny new-ness.
-
Escuelas Linux 8.0 Now Available
Just in time for its 25th anniversary, the developers of Escuelas Linux have released the latest version.
-
LibreOffice 7.5 Loaded with New Features and Improvements
The favorite office suite of the Linux community has a new release that includes some visual refreshing and new features across all modules.
-
The Next Major Release of Elementary OS Has Arrived
It's been over a year since the developers of elementary OS released version 6.1 (Jólnir) but they've finally made their latest release (Horus) available with a renewed focus on the user.
-
KDE Plasma 5.27 Beta Is Ready for Testing
The latest beta iteration of the KDE Plasma desktop is now available and includes some important additions and fixes.
-
Netrunner OS 23 Is Now Available
The latest version of this Linux distribution is now based on Debian Bullseye and is ready for installation and finally hits the KDE 5.20 branch of the desktop.
-
New Linux Distribution Built for Gamers
With a Gnome desktop that offers different layouts and a custom kernel, PikaOS is a great option for gamers of all types.
-
System76 Beefs Up Popular Pangolin Laptop
The darling of open-source-powered laptops and desktops will soon drop a new AMD Ryzen 7-powered version of their popular Pangolin laptop.
-
Nobara Project Is a Modified Version of Fedora with User-Friendly Fixes
If you're looking for a version of Fedora that includes third-party and proprietary packages, look no further than the Nobara Project.