Open Manual of Markdown Style

Author

Julien Dutant and the Dialoa team

Preface

The Open Manual of Markdown Style by Dialoa

This book is an open manual of style for scholarly publishing using markdown. Open because it focuses on open-source software tools and is targeted at open-access publishers. Of markdown style because it combines style and technical advice for producing professional-quality publications using markdown. The manual itself is open-source, open-access and written in markdown.

Presentation

The OMMS aims to make markdown-based professional-quality publishing available to academic teams with no advanced technical knowledge. It explains how to convert manuscripts into, or author them as, markdown documents, and turn them into beautifully typeset outputs in multiple print and digital formats.

No prior knowledge of markdown is required; authoring and copyediting can largely be done using visual tools. Production, however, realistically requires some technical knowledge (CSS for web output, LaTeX for print output).

Relation with Quarto

The OMMS overlaps with, and complements, the excellent Quarto documentation.

  • The OMMS focuses on copyediting and production. It is aimed at small publishing outfits rather than authors - though you can use it to write a thesis.

  • The OMMS gives prescriptive style and typesetting advice. It’s a manual of style rather than technical documentation.

Status

The manual is a work in progress. It is used to produce the open-access philosophy journal Dialectica and compiles the solutions we’ve adopted to deal with a range of typesetting problems. It is fairly extensive but far from complete.

Edit the guide

You’re welcome to edit the guide. To do so:

  • Install Quarto. Some package managers have it (brew install quarto on MacOs, choco install quarto on Windows, but not on Linux.) See 30  Dialectica new house style outputs on package managers.
  • Open the guide folder in RStudio (or Visual Code, if you use Quarto with that).
  • Chapters are listed in _quarto.yaml . If you create a new chapter you need to add it here.
  • Chapter files are in the chapters folder - obviously. Numbers in their names are for convenience: they ensure that chapters in the folder appear in the same order as they appear in the book.
  • Chapters can be edited in visual or source mode. They’re “Quarto markdown” (.qmd) files but that’s just like Pandoc markdown.
  • To render a chapter open and it and use Render > Render HTML. You’ll see the output in RStudio’s preview pane.
  • To render the whole book Build > Render Book or open the index.qmd file and do Render > Render HTML.

Credits and license

Developed by the Dialoa team and philosophie.ch.

Copyright 2021-23 Julien Dutant

Creative Commons Attribution 4.0 International license This work licensed under a Creative Commons Attribution 4.0 International license.