In that spirit, here's how I used the venerable pandoc to convert my MSc dissertation from .md into a variety of more readable formats.

Prep

I've no idea what you already have installed on your system but, at a minimum, you need to install the latest version of pandoc and you'll need a modern version of the weasyprint library.

I found pandoc's dependencies... interesting. Depending on your operating system, you may find yourself having to install all sorts of esoteric libraries.

Commands

This is what you'll need to run to generate the outputs. I'll show you the commands, then what you need in each file.

HTML:

pandoc dissertation.md \
   --citeproc --metadata-file=metadata.yml --embed-resources --standalone \
    -o ../output/dissertation.html

ePub:

pandoc dissertation.md \
   --citeproc --metadata-file=metadata.yml --epub-embed-font=fonts/font.ttf \
   -o ../output/dissertation.epub

PDF:

pandoc dissertation.md \
   --citeproc --metadata-file=metadata.yml --pdf-engine=weasyprint \
   -o ../output/dissertation.pdf

Metadata

You'll need a metadata file called metadata.yml. It must start and finish with ---

---
lang: en-GB
title: My awesome dissertation
bibliography: Bibliography.bib
csl: harvard-cite-them-right.csl
link-citations: true
reference-section-title: References
author: Terence Eden
creator: Terence Eden
rights:  🄯 CC BY-NC 4.0
keywords: [Some, comma, separated, keywords]
date: 2023-04-24
description: A dissertation about stuff
css: style.css
cover-image: media/cover.jpg
---

Hopefully all those entries are self-explanatory. Now let's go into each extra file that this requires!

Bibliography

I assume that you're using Zotero or some other citation manager. Export all your citations using in Better BibTex format as Bibliography.bib.

You may need to install a Better BibTex plugin.

Citation Style Language - CSL

Your citation manager probably already has your preferred CSL format. If not, you can download the .csl file from Zotero or from the CSL GitHub.

Layout CSS

The layout for HTML, ePub, and PDF is all controlled by CSS. Here's a minimum viable stylesheet. It's designed for A4 paper as well as screens. Figures and tables stay on their own printed page. Sections also get a page-break.

I've commented any interesting bits. Feel free to add to it for your own use:

@page {
    /* Set paper options */
    size: A4;
    margin: 1cm;
}

@media print {
    /* Stop figures & tables from being broken */
    figure, table {
      break-inside: avoid-page;
    }

    /*  Put each section on a new page*/
    h2 {
        break-before: always;
    }
}

@media screen {
    body {
        max-width: 45em;
        margin-left: auto;
        margin-right: auto;
    }
}

@font-face {
    font-family: "My-Font";
    /* WOFF2 for web, TTF for ePub */
    src:
        url("fonts/font.ttf"),
        url("fonts/font.woff2") format("woff2");
}

html {
    font-size: 1em;
}

body {
    text-align: justify;
    font-family: "My-Font", sans-serif;
}

a {
    color: #001aff; 
}

img {
    max-width: 100%;
    margin: auto;
    display: block;
}

/* Make references spaced out better */
#refs > div {
    padding-bottom: 1em;
}

figure {
    border: 1px solid gray;
    max-width: fit-content;
}

figcaption {
    font-size: .9em;
    color: rgb(24, 24, 24);
    text-align: center;
}

table {
    width: 100%;
    border-collapse: collapse;
    font-size: .9em;
}
td {
    padding: .5em;
    border: 1px solid black;
    text-align: left;
}

h2 {
    text-align: left;
}

p {
    margin:.5em;
}

Fonts

If you want a custom font, you'll need it in TTF and WOFF2 format. Not all eReaders can use WOFF2, so TTF is needed as a fallback. I recommend using FontSquirrel to generate the font formats.

Markdown

OK, now here we go! You can use a mix of Markdown and HTML.

A few points that may not be obvious:

• No need for a # top level heading. Pandoc will insert one for you.
• No need for a table of contents. Again, let Pandoc doc it.
• You will need to manually add lists for figures, acronyms, tables, glossary, etc.
• I like to use internal links in Markdown. For example

## 1. Introduction {#1-introduction}

### 1.1 Context {#1-1-context}

• That lets you write as can be seen [in Methodology](#2-Methodology)
• Speaking of which, I couldn't find a good way to do figures and captions in Markdown, so I reverted to HTML:

<figure id="figure-01">
   <figcaption>Figure 01 - A fictional depiction of 3D visualisations of Cybersecurity interfaces</figcaption>
   <img src="media/jurassic.jpg" width="" alt="Screenshots from the movie Jurassic Park. A young woman looks at a 3D display on a monitor. She exclaims It's a UNIX System. I know this.">
   <figcaption>[@spielbergJurassicPark1993]</figcaption>
</figure>

• Notice the way citations are done there? I, again, use Zotero and a VS Code plugin to insert citations. Don't attempt to do them by hand!
• No need to add your own list of references. Pandoc will add them where it sees:

<div id="refs">
## References
</div>

So, a sample document will look something like:

## 1. Introduction {#1-introduction}

### 1.1 Context {#1-1-context}
Blah blah blah

![Alt text.](media/photo.jpg)

Or

<figure id="figure-01">
   <figcaption>Figure 01</figcaption>
   <img src="media/example.jpg" width="" alt="Description.">
   <figcaption>[@spielbergJurassicPark1993]</figcaption>
</figure>

<div id="refs">
## References
</div>

## Appendix
* Some
* Bullets

Is it worth it?

Well, now, there's the question! You can just export these formats from Google Docs, Office 365, etc. But this method gives you much more control over what the end-product looks like.

Isn't yak-shaving fun⸮

So, you want to write your dissertation or thesis in Markdown. But how do you manage all your citations?

1. Install Zotero
2. Install the Better BibTex plugin
3. Restart Zotero. The BBT plugin will launch a configuration screen - use it to set your preferences
4. Install VS Code (or VS Codium)
5. Install the VS Code Zotero plugin

Now, when you want to enter a citation in Markdown, the combined plugins will generate something like this:

## Abstract

Space is really big @adamsHitchhiker1979

That @adamsHitchhiker1979 is the citation.

Formatting citations

You want to export your Markdown to something like ePub or PDF with nicely formatted citations like (Adams, 1979)

Use Pandoc!

1. Install Pandoc
2. In Zotero, use File → Export Library. Export in Better BibTex format as test.bib.

Add the following configuration section to the top of your Markdown file:

---
bibliography: test.bib
...

Run the following command:

pandoc --citeproc test.md -o test.epub

Hey presto! You now have a nicely formatted ePub with all the citations in your preferred format, and the bibliography at the end.

Format the citations better

The citations don't look the way I want them to!

1. Download your preferred Citation Style from Zotero, save it as whatever.csl
2. Add the following into your Markdown file's configuration section csl: whatever.csl
3. Important Make sure that your citations are wrapped in [ and ] otherwise Pandoc will mess things up. See the Pandoc Citations Extension for more details.

Your Markdown should look something like this:

---
bibliography: test.bib
csl: whatever.csl
link-citations: true
...

# Intro

Computers are complicated [@verletComputerExperimentsClassical1967].

Then run pandoc --citeproc test.md -o test.epub - you can change the file type to html, pdf, or anything else your system supports.

Make it look even nicer

This is the boilerplate that I use.

---
bibliography: test.bib
csl: whatever.csl
link-citations: true
reference-section-title: References
title: My brilliant title
...

# Intro

Computers are complicated [@verletComputerExperimentsClassical1967].

## Something

More info [@smithEvolutionInnovationCapability2017]

<div id="refs">
## References
</div>

## The End
Goodbye!

That gives you a title, ensures that all in-text citations link down to the references, and puts the references somewhere other than the end. Here's the HTML it produces using pandoc --citeproc test.md -o bib.html :

<h1 id="intro">Intro</h1>
<p>Computers are complicated <span class="citation" data-cites="verletComputerExperimentsClassical1967">(<a
         href="https://shkspr.mobi/blog/2022/11/zotero-citations-in-markdown-publishing-to-epub-or-pdf/#ref-verletComputerExperimentsClassical1967" role="doc-biblioref">Verlet, 1967</a>)</span>.</p>
<h2 id="something">Something</h2>
<p>More info <span class="citation" data-cites="smithEvolutionInnovationCapability2017">(<a
         href="https://shkspr.mobi/blog/2022/11/zotero-citations-in-markdown-publishing-to-epub-or-pdf/#ref-smithEvolutionInnovationCapability2017" role="doc-biblioref">Smith <em>et al.</em>, 2017</a>)</span>
</p>
<div id="refs" class="references csl-bib-body" role="doc-bibliography">
   <h2 id="references">References</h2>
   <div id="ref-smithEvolutionInnovationCapability2017" class="csl-entry" role="doc-biblioentry">
      Smith, C. <em>et al.</em> (2017) <span>‘The <span>Evolution</span> of an
         <span>Innovation Capability</span>’</span>, <em>Research-Technology
         Management</em>, 60(2), pp. 26–35. Available at: <a
         href="https://doi.org/10.1080/08956308.2017.1276388">https://doi.org/10.1080/08956308.2017.1276388</a>.
   </div>
   <div id="ref-verletComputerExperimentsClassical1967" class="csl-entry" role="doc-biblioentry">
      Verlet, L. (1967) <span>‘Computer "<span>Experiments</span>" on
         <span>Classical Fluids</span>. <span>I</span>. <span>Thermodynamical
            Properties</span> of <span>Lennard-Jones Molecules</span>’</span>,
      <em>Physical Review</em>, 159(1), pp. 98–103. Available at: <a
         href="https://doi.org/10.1103/PhysRev.159.98">https://doi.org/10.1103/PhysRev.159.98</a>.
   </div>
</div>
<h2 id="the-end">The End</h2>
<p>Goodbye!</p>

If that was useful to you - or if you think you know a better way - please drop a comment in the box.

For example ([Smith, 1984](https://doi.org/.....))

This is possible, if you're willing to hack around with CSL - the Citation Style Language.

Here's a fragment of CSL that I've adapted from Brenton M. Wiernik's zotero-tools/apa-doi-in-text.csl

  <macro name="url-intext">
    <choose>
      <if variable="DOI">
        <text variable="DOI" prefix="https://doi.org/"/>
      </if>
      <else-if variable="URL">
        <text variable="URL"/>
      </else-if>
      <else>
        <text value=""/>
      </else>
    </choose>
  </macro>
  <citation et-al-min="4" et-al-use-first="1" disambiguate-add-year-suffix="true" disambiguate-add-names="true" disambiguate-add-givenname="true" collapse="year">
    <sort>
      <key macro="year-date"/>
    </sort>
    <layout delimiter="; ">
      <group prefix="([" suffix="]" delimiter=", ">
        <group delimiter=", ">
          <text macro="author-short"/>
          <text macro="year-date"/>
        </group>
        <group>
          <label variable="locator" form="short" suffix=" "/>
          <text variable="locator"/>
        </group>
      </group>
      <text macro="url-intext" prefix="(" suffix="))"/>
    </layout>
  </citation>

I'm a neophyte at CSL, so I'm sure there is a better way to do it. Essentially, this is creating a group, starting with ([. Inside that it places the author(s) and date. It ends the group with ] - then obtains the URl from a macro, surrounds it by ( and )), then prints it.

There are a few bugs. If there is no URl, you might end up with mismatched brackets. But it seems to work OK.

My University insists on Cite Them Right's Harvard style - so that's what I'm using.

I've released a Zotero CSL file on GitLab if you want to use it. Feedback is very welcome - because I have no idea what I'm doing!