MD bib referencing workflow and formatting edits. Renamed markdown-formattting to md-formatting !publish!
This commit is contained in:
parent
d32d5bdf87
commit
a2e5fa90a5
8 changed files with 187 additions and 482 deletions
|
|
@ -15,7 +15,7 @@ This project implements *Sandpoints*, an open source framework for open and coll
|
|||
Key features:
|
||||
1. *Sandpoints* requires no programming.
|
||||
2. Creating new content and compiling a website project are done with simple terminal commands.
|
||||
3. Content is added with , which are easy to read, write, and edit, and organized in folders by type.
|
||||
3. Content is added with , which are easy to read, write, and edit, and organized in folders by type.
|
||||
4. *Sandpoints* implements hypertext, including backlinks (bidirectional hyperlinks), and allows non-linear content traversal, for example via browsing links, backlinks, and keywords.
|
||||
5. *Sandpoints* is structured around a triadic hierarchy, here this is *Journal>Issue>Article*.
|
||||
6. Collaboration, version control, and backup are achieved via Git.
|
||||
|
|
|
|||
|
|
@ -72,7 +72,7 @@ This will download a copy of all the material of the repository placed inside a
|
|||
|
||||
# Editing the site
|
||||
|
||||
To edit the site it's recommended use a Markdown or other text editor such as [Obsidian][] or [VS Code][]. Editing only entails working with Markdown files within the `/content/` folder of the project. See also the guides about , , and .
|
||||
To edit the site it's recommended use a Markdown or other text editor such as [Obsidian][] or [VS Code][]. Editing only entails working with Markdown files within the `/content/` folder of the project. See also the guides about , , and .
|
||||
|
||||
## Committing changes
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ Here is an outline:
|
|||
- Content in *Hugo* and *Sandpoints* is managed with *Markdown files*.
|
||||
- Markdown is an open specification for plain-text human readable files.
|
||||
- Markdown files can be opened and edited by any text editor.
|
||||
- Markdown formatting syntax is simple and quite easy to learn (see also ).
|
||||
- Markdown formatting syntax is simple and quite easy to learn (see also ).
|
||||
- Since they are plain-text, they are extremely lightweight (this file is 6KB).
|
||||
- They can easily serve distributed collaboration through version control (i.e. [Git][]).
|
||||
- They can be rendered to many other formats with tools such as [Pandoc][] (e.g. to pdf, docx, etc.), which can also compile bibliographic references.
|
||||
|
|
|
|||
|
|
@ -1,427 +0,0 @@
|
|||
---
|
||||
title: "Markdown formatting guide"
|
||||
date: "2023-06-28T01:58:32+03:00"
|
||||
author: "anybody"
|
||||
contributors: ["constantinos-miltiadis.md"]
|
||||
draft: false
|
||||
keywords:
|
||||
- markdown guide
|
||||
- guide
|
||||
abstract: |
|
||||
This is a Markdown formatting guide.
|
||||
publishDate: "2021-06-28T01:58:32+03:00"
|
||||
---
|
||||
|
||||
[Pandoc]: https://pandoc.org/ "universal document converter."
|
||||
|
||||
# What is Markdown
|
||||
|
||||
Markdown is an open standard for a flexible, human-readable, lightweight mark-up language for formatting text. It was developed by John Gruber and the late Aaron Swartz, and released in 2004. Markdown files have the extension ‘*.md*’ and consist of plain text, therefore they can be opened, edited and read using any text editor, rudimentary or otherwise.
|
||||
|
||||
Since its release in 2004 Markdown has been adopted widely for multiple applications -- for example by *GitHub* (for repository readme files), by R (as R Markdown), for note-taking and collaborative writing applications (e.g. *Obsidian*, *hackmd.io*, *Zotero*, *Nextcloud*), for chat applications (e.g. *Element*), and also by static website frameworks (e.g. *Hugo* and *Jekyll*).
|
||||
|
||||
Although one can read and write Markdown using a basic notepad, it is recommended to use a text editor with Markdown support such as [Obsidian](https://obsidian.md/), or [Visual Studio Code](https://code.visualstudio.com/.). For an online Markdown editor see [hackmd.io](https://hackmd.io/).
|
||||
|
||||
Markdown documents can be converted to multiple other document formats. Tools like [Pandoc][] allow working with and compiling bibliographic references, and can render Markdown files into pdf, docx, txt, html, epub, and many more (see ).
|
||||
|
||||
# Markdown formatting guide
|
||||
|
||||
The following demonstrates how to write in Markdown and shows how Markdown is rendered by this website.
|
||||
For external resources on Markdown see the [Notes section](#notes).
|
||||
|
||||
## Writing in Markdown [draft]
|
||||
Markdown is a plain text format, intended for digital text. Unlike conventional word processors that go by the
|
||||
|
||||
that simulate writing on paper and follow the what-you-see-is-what-you-get (WYSIWYG) concept.
|
||||
|
||||
Markdown is intended to facilitate writing and reading.
|
||||
|
||||
em dash -- with some content inside -- is useful.
|
||||
|
||||
*Formatting:*
|
||||
```
|
||||
This will
|
||||
appear as
|
||||
a single
|
||||
line.
|
||||
```
|
||||
|
||||
*Appearance:*
|
||||
This will
|
||||
appear as
|
||||
a single
|
||||
line.
|
||||
|
||||
## Text formatting
|
||||
|
||||
| Formatting | Appearance|
|
||||
|-|-|
|
||||
|`normal text`| normal text|
|
||||
| `*emphasis*`| *emphasis*|
|
||||
| `**bold**`| **bold**|
|
||||
| `***bold emphasis***`| ***bold emphasis***|
|
||||
| `~~strikethrough~~`| ~~strikethrough~~|
|
||||
| \`code blocks\`| `code blocks`|
|
||||
| `something<sup>superscript</sup>` | something<sup>superscript</sup>|
|
||||
| `something<sub>subscript</sub>` | something<sub>subscript</sub> |
|
||||
| `\* \~ \[ \{ \#` | \* \~ \[ \{ \#|
|
||||
|
||||
## Headings
|
||||
|
||||
Headings make use of the hashtag character, as follows:
|
||||
|
||||
```
|
||||
# Heading
|
||||
## Sub-heading
|
||||
### Sub-sub-heading
|
||||
```
|
||||
*Note that a space is required between the hashtag character and the header text.*
|
||||
## Lists
|
||||
|
||||
Markdown bullet lists use the dash/minus symbol as in:
|
||||
```
|
||||
- bullet 1
|
||||
- bullet 2
|
||||
- sub-bullet 2.1
|
||||
```
|
||||
|
||||
Numbered lists start with a number followed by a period as in:
|
||||
```
|
||||
1. List item 1,
|
||||
2. List item 2,
|
||||
1. Sub-item 2.1
|
||||
```
|
||||
|
||||
|
||||
|
||||
Bullet list appearance:
|
||||
- bullet 1
|
||||
- bullet 2
|
||||
- sub-bullet 2.1
|
||||
|
||||
Numbered list appearance:
|
||||
1. List item 1,
|
||||
2. List item 2,
|
||||
1. Sub-item 2.1
|
||||
|
||||
*Note that both cases require a space before the list item text.
|
||||
To add depth, add two spaces or a tab in a subsequent list item.
|
||||
Lists should not have empty lines between items.*
|
||||
|
||||
## Quotes [draft]
|
||||
|
||||
*Blockquotes:*
|
||||
> This is a blockquote. Block quotes should be used when the quoted text is 40 words or more. Otherwise use in-line quotes. In all cases quotes are followed by a reference (Author et. al 2010).
|
||||
|
||||
*Blockquote formatting:*
|
||||
|
||||
```
|
||||
> This is a blockquote. Block quotes should be used when the quoted text is 40 words or more. Otherwise use in-line quotes. In all cases quotes are followed by a reference (Author et. al 2010).
|
||||
```
|
||||
|
||||
*Inline quotes:*
|
||||
For shorter quotes, use inline quotes, between "quotation marks" and should be followed by a reference (Author 2015).
|
||||
|
||||
Note that:
|
||||
- > If *you emphasized some text yourself you need to mention that in the reference* (Author et al. 2010; emphasis mine).
|
||||
- > Or if your quote includes an *emphasis found in the original* (Author et al. 2020, emphasis in original).
|
||||
- If your inline quote includes a world
|
||||
|
||||
- [how to mention 'et al.' : Author and colleagues or Author et al.?]
|
||||
- [example of normal in-line quote]
|
||||
- [omitting author from ref] Discussing x, Author described that "this is a good case of" (2010).
|
||||
- [example of quote edit]
|
||||
- [example of transcript]
|
||||
- [example of emphasis]
|
||||
|
||||
## Images
|
||||
|
||||
Recommended and supported image formats are:
|
||||
- PNG for rasterized content.
|
||||
- SVG for vector content.
|
||||
|
||||
Avoid image formats that are lossy and can introduce artifacts (e.g. JPG).
|
||||
|
||||
*Image formatting pseudocode*:
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
The examples below use the same graphic put together in Illustrator and exported to:
|
||||
- SVG (file size: 3KB; export optimized for text; selectable text)
|
||||
- PNG (file size: 56KB; export resolution x3 @ 2100x900; transparent background)
|
||||
|
||||
*Image formatting example*:
|
||||
```
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
*Appearance*:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
*Note: to view the full resolution version of an image, right click on an image and select "Open image in new tab".*
|
||||
|
||||
## Tables
|
||||
|
||||
*Table formatting*:
|
||||
```
|
||||
| Header 1 | Header 2 | Header 3|
|
||||
|--|--|--|
|
||||
| This | is | a|
|
||||
| table | with | content.|
|
||||
```
|
||||
|
||||
*Table appearance*:
|
||||
| Header 1 | Header 2 | Header 3|
|
||||
|--|--|--|
|
||||
| This | is | a|
|
||||
| table | with | content.|
|
||||
|
||||
|
||||
*Note: The number of dashes in the second row, as well as the white space inside individual cells are arbitrary, and can modified to make the table more easily readable while writing/editing.*
|
||||
|
||||
|
||||
### Table column alignment
|
||||
|
||||
In case alignment is important, it can be assigned per column.
|
||||
|
||||
*Formatting*:
|
||||
```
|
||||
| Header 1 | Header 2 | Header 3|
|
||||
|:--|:--:|--:|
|
||||
| left | center | right|
|
||||
```
|
||||
|
||||
*Appearance*:
|
||||
|
||||
| Header 1 | Header 2 | Header 3|
|
||||
|:--|:--:|--:|
|
||||
| left | center | right|
|
||||
|
||||
### Headerless tables
|
||||
|
||||
For a table without headers, leave the initial row empty.
|
||||
|
||||
*Formatting*:
|
||||
|
||||
```
|
||||
| | |
|
||||
|-|-|
|
||||
|A|table|
|
||||
|without|headers|
|
||||
```
|
||||
|
||||
*Appearance*:
|
||||
|
||||
| | |
|
||||
|-|-|
|
||||
|A|table|
|
||||
|without|headers|
|
||||
|
||||
## Links
|
||||
|
||||
### Hyperlinks
|
||||
|
||||
*Hyperlink formatting*:
|
||||
|
||||
```
|
||||
[hyperlink caption](https://hyperlink-destination.org)
|
||||
```
|
||||
|
||||
*Hyperlink appearance*:
|
||||
|
||||
[hyperlink caption](https://hyperlink-destination.org)
|
||||
|
||||
*Note: Do not omit the `http://` or `https://` part of the URL.*
|
||||
|
||||
### Internal links to other sections of this document
|
||||
|
||||
To link to another section of the same document, use the hyperlink syntax.
|
||||
For destination use the heading of the section, in lowercase, replacing spaces with dashes. Prefix that with only one hashtag character, regardless of the depth of the heading.
|
||||
|
||||
Formatting example (a link to the first section of this document):
|
||||
[go to 'What is Markdown'](#what-is-markdown).
|
||||
|
||||
Syntax:
|
||||
```
|
||||
[go to 'What is Markdown'](#what-is-markdown)
|
||||
```
|
||||
### Links to other entries of this site
|
||||
|
||||
The convention for links to other entries of this project is:
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
Examples:
|
||||
```
|
||||
|
||||
|
||||
```
|
||||
Appearance:
|
||||
|
||||
|
||||
|
||||
|
||||
### Footnotes
|
||||
|
||||
The syntax for inserting a footnote is `[^key]`, where `key` can be arbitrary. The content of the footnote can be placed anywhere in the document, and follows the syntax `[^key]: Footnote content.`
|
||||
|
||||
|
||||
Here is a sentence with a footnote.[^fn] Footnotes are placed *after* a period or comma, like here.[^fn] Footnotes can be reused, and Sandpoints will generate dynamic backlinks to all mentions of the same footnote.[^fn]
|
||||
|
||||
[^fn]: This is the text of a footnote, used 3 times.
|
||||
|
||||
Formatting:
|
||||
|
||||
```
|
||||
Here is a sentence with a footnote.[^fn]
|
||||
[^fn]: This is the text of a footnote, used 3 times.
|
||||
```
|
||||
|
||||
### Links to Library items
|
||||
|
||||
[Library]: /library/BROWSE_LIBRARY.html "Project library."
|
||||
|
||||
Library items can be referenced inside entries of this website.
|
||||
To reference a library item inside a Markdown entry of this project do:
|
||||
|
||||
```
|
||||
.
|
||||
```
|
||||
|
||||
Where `the-book-id` is a placeholder for the unique id of a library item (in the style of `625e5562-38bc-4497-adaa-5142ef810c4a`). To get the id of an item, go to the [Library][], find the item you want to reference, and copy the last part of it’s URL after `.../book/`.
|
||||
|
||||
Example library reference:
|
||||
```
|
||||
|
||||
```
|
||||
Appearance:
|
||||
|
||||
|
||||
|
||||
*Note: the formatting convention `` will automatically generate a bibliographic citation (as in the example above). To use a custom text associated with a library reference add some text in the square brackets of the link as in ``.*
|
||||
|
||||
## Code blocks
|
||||
|
||||
Code blocks are segments that ignore Markdown formatting, and will be compiled verbatim.
|
||||
For inline code blocks enclose text within backticks, as in:
|
||||
|
||||
```
|
||||
'inline code block'
|
||||
```
|
||||
that will appear as:
|
||||
`inline code block`
|
||||
|
||||
For multiline code blocks enclose text between two sets of triple backticks (<code> ```</code> ).
|
||||
```
|
||||
code blocks will ignore markdown formatting, e.g.
|
||||
![]() ## ** {{}} [^footnote]
|
||||
|
||||
```
|
||||
|
||||
|
||||
## Embedded content [THIS WE NEED TO TALK ABOUT]
|
||||
|
||||
Hugo can embed a range of different media via shortcodes (see [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/)). Note that embedded media cannot be exported to PDF or printed.
|
||||
|
||||
*More importantly, embedded content could disappear at any time. To properly archive media it is recommended to add such items to the [Library][], and refer to them via a link -- this can be facilitated by editors.*
|
||||
|
||||
---
|
||||
|
||||
YouTube, and Vimeo videos can be easily embedded using video ids (the last bit of their URLs). Examples:
|
||||
|
||||
{{< youtube UEoDJ1v6U6U >}}
|
||||
<figcaption>Video 1: Video caption.</figcaption>
|
||||
|
||||
{{< vimeo 55073825 >}}
|
||||
<figcaption>Video 2: Video caption.</figcaption>
|
||||
|
||||
Formatting (*note: remove \* characters*):
|
||||
```
|
||||
{{*< youtube UEoDJ1v6U6U >*}}
|
||||
<figcaption>Video 1: Video caption.</figcaption>
|
||||
|
||||
{{*< vimeo 55073825 >*}}
|
||||
<figcaption>Video 2: Video caption.</figcaption>
|
||||
```
|
||||
|
||||
### GitHub Gists
|
||||
|
||||
Example:
|
||||
{{< gist cmiltiadis 0c458dcea8b8569398f5988b0151636c >}}
|
||||
<figcaption>Codegist 1: Gist caption.</figcaption>
|
||||
|
||||
Formatting (*note: remove \* characters*):
|
||||
```
|
||||
{{*< gist username gistId >*}}
|
||||
<figcaption>Codegist 1: Gist caption.</figcaption>
|
||||
```
|
||||
|
||||
### Videogame embedding [DRAFT]
|
||||
|
||||
Implement Unity WebGL embed described here:
|
||||
https://michaelcassidy.net/post/hugo-shortcode-for-embedding-unity-webgl-players-updated-with-code/
|
||||
|
||||
This should allow embedding games as follows (note: square brackets need to be replaced with curly brackets):
|
||||
```
|
||||
> [[< unity-webgl-player game
|
||||
> Title="My cool game"
|
||||
> width="1024" height="576"
|
||||
> buildURL="https://somewhere.com/path/to/files/Build"
|
||||
> buildFileName="webgl"
|
||||
> playerID="" >]]
|
||||
```
|
||||
## Other formatting
|
||||
|
||||
The following includes formatting that might be useful while writing, but has limited application in published material.
|
||||
|
||||
### Horizontal dash
|
||||
|
||||
Formatting
|
||||
```
|
||||
---
|
||||
```
|
||||
|
||||
Appearance
|
||||
|
||||
---
|
||||
Note: Leave an empty line before a horizontal dash.
|
||||
|
||||
### Toggle lists
|
||||
|
||||
- [ ] Unchecked toggle item.
|
||||
- [x] Checked toggle item.
|
||||
|
||||
```
|
||||
- [ ] Unchecked toggle item.
|
||||
- [x] Checked toggle item.
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
To comment out some content, so that it's ignored use HTML comment formatting as follows:
|
||||
```
|
||||
<!-- This is a comment and will not appear-->
|
||||
|
||||
<!--
|
||||
Comments
|
||||
can be
|
||||
multiline.
|
||||
-->
|
||||
```
|
||||
|
||||
|
||||
# Notes
|
||||
- For the original Markdown specification see [Markdown specification (John Gruber, 2004)](https://daringfireball.net/projects/markdown/).
|
||||
- For a Markdown formatting guide see [Basic Syntax (markdownguide.org)](https://www.markdownguide.org/basic-syntax/).
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Markdown Workflow"
|
||||
title: "Markdown bibliographic referencing workflow"
|
||||
date: "2023-07-14T20:21:29+03:00"
|
||||
author: "anybody"
|
||||
contributors: ["constantinos-miltiadis.md"]
|
||||
|
|
@ -8,91 +8,178 @@ keywords:
|
|||
- guide
|
||||
- markdown guide
|
||||
abstract: |
|
||||
This article outlines a workfow for compiling bibliography for articles written in Markdown. All tools involved are free, open source, and cross platform.
|
||||
This article outlines a workflow for incorporating bibliographic citations/references in Markdown documents, and exporting new documents with compiled bibliographies according to specific citation styles. All tools involved in this pipeline are free, open source, and cross platform.
|
||||
---
|
||||
|
||||
[Better Bibtex]: https://retorque.re/zotero-better-bibtex/ "Extension for Zotero for managic bibliographic data ."
|
||||
[Better Bibtex]: https://retorque.re/zotero-better-bibtex/ "an extension for Zotero for managing bibliographic data, especially text-based document authoring toolchains"
|
||||
[Zotero]: https://www.zotero.org/ "free and open source, cross-platform citation management software."
|
||||
[Pandoc]: https://pandoc.org/ "universal document converter."
|
||||
[Pandoc]: https://pandoc.org/ "universal document converter"
|
||||
|
||||
|
||||
<!-- try
|
||||
output: html_document
|
||||
bibliography: references.bib
|
||||
-->
|
||||
|
||||
# Introduction
|
||||
|
||||
This guide describes how to work with bibliographic references in  writing workflows. It outlines how to incorporate references, and how compile and export in various document formats (PDF, DOCX, MD, etc.), using any formal citation style.
|
||||
This guide outlines a workflow for incorporating bibliographic referencing (citations and references) in  documents. The general idea is incorporating citation keys in a Markdown document, and then rendering the bibliography by generating a new document against a bibliographic collection (`bib` file), and a citation style (`csl` file).
|
||||
The following describes:
|
||||
- creating and exporting a bibliography collection with [Zotero][];
|
||||
- using citation keys in a Markdown document;
|
||||
- getting a citation style file;
|
||||
- exporting new documents (e.g. PDF, DOCX, MD, etc.) with [Pandoc][], where citations and bibliographic references are formatted as per any specific citation style.
|
||||
|
||||
All tools involved are free, open source, and cross-platform.
|
||||
|
||||
---
|
||||
|
||||
Note: A *citation* is used in the body of the text to refer to some external source. A *reference* is placed in the "References" or "Bibliography" section of the document providing the full information for a citation. Citations and references are formatted according to a citation style.
|
||||
For example, for an 'author-year' citation style like *Chicago* in-text citations look like: Khaled et al. (2018), or (Khaled et al. 2018). According to the same citation style, the reference for that citation is:
|
||||
- Khaled, Rilla, Jonathan Lessard, and Pippin Barr. ‘Documenting Trajectories in Design Space: A Methodology for Applied Game Design Research’. In _Proceedings of the 13th International Conference on the Foundations of Digital Games_, 1–10. Malmö Sweden: ACM, 2018. [https://doi.org/10.1145/3235765.3235767](https://doi.org/10.1145/3235765.3235767).
|
||||
|
||||
# Requirements
|
||||
|
||||
1. Some Markdown editor (see ).
|
||||
1. Some Markdown editor for authoring Markdown documents (see ).
|
||||
2. [Zotero][] -- free and open source cross platform citation management software.
|
||||
3. [Better Bibtex] -- "an extension for Zotero ... that makes it easier to manage bibliographic data, especially for people authoring documents using text-based toolchains (e.g. based on [LaTeX](https://www.latex-project.org/) / [Markdown](https://www.markdownguide.org/)").
|
||||
4. [Pandoc][] -- command line tool; "universal document converter".
|
||||
4. [Pandoc][] -- "universal document converter"; a command line tool for converting between different document formats (e.g. Markdown to PDF or DOCX), and compiling bibliographic references.
|
||||
|
||||
|
||||
# Aggregate and export bibliography collection
|
||||
## Pandoc installation & upgrade {#pandoc-install}
|
||||
|
||||
The following outlines how to generate a `bib` file from a Zotero collection:
|
||||
[Chocolatey]: https://chocolatey.org/ "Free and open source package manager for Windows."
|
||||
[Homebrew]: https://brew.sh/ "Free and open source package manager for macOS."
|
||||
|
||||
1. In Zotero, create a new collection (titled say `mycollection`), and add all the items you want to reference in your document.
|
||||
2. With [Zotero][] and [Better Bibtex][] installed, each entry in your Zotero database should have citation key:
|
||||
Pandoc is a command line tool that can be installed via a downloadable installer or through the terminal (see [Installing pandoc](https://pandoc.org/installing.html)).
|
||||
To check if pandoc is installed, and which version is installed, open a terminal and do:
|
||||
```
|
||||
pandoc --version
|
||||
```
|
||||
|
||||
If pandoc is not recognized as a valid command, go ahead and install pandoc. Otherwise, upgrade pandoc to the latest release.
|
||||
|
||||
### Installation
|
||||
|
||||
Installing via a terminal requires a package manager (e.g. [Chocolatey][] for Windows, or [Homebrew][] for macOS).
|
||||
|
||||
- For Windows, using the package manager [Chocolatey] do:
|
||||
```
|
||||
choco install pandoc
|
||||
```
|
||||
- For macOS, using the package manager [Homebrew][], do:
|
||||
```
|
||||
brew install pandoc
|
||||
```
|
||||
|
||||
### Upgrade
|
||||
|
||||
To upgrade [Pandoc][], if it was installed via an installer, download and run the latest installer.
|
||||
|
||||
If it was installed via terminal, it can be upgraded with a single command.
|
||||
- For Windows:
|
||||
```
|
||||
choco upgrade pandoc
|
||||
```
|
||||
- For macOS:
|
||||
```
|
||||
brew upgrade pandoc
|
||||
```
|
||||
|
||||
Verify the version of pandoc with the command:
|
||||
```
|
||||
pandoc --version
|
||||
```
|
||||
|
||||
# Create and export a bibliography collection
|
||||
|
||||
|
||||
This section outlines how to create a bibliography collection in Zotero and export it to a `bib` file.
|
||||
|
||||
1. In Zotero, create a new collection (titled say `mycollection`).
|
||||
2. Add to your collection all items you want to reference (by drag and drop to collection, or right click > Add to Collection).
|
||||
3. With [Zotero][] and [Better Bibtex][] installed, each entry in your Zotero database should have a unique citation key displayed at the top of its Info section (image below). Use this key as in `@key` (or `@khaled2018`) to cite this item in your Markdown document ([further instructions below](#cite)).
|
||||
|
||||
3. To reference an item in a Markdown file, just prefix the citation key with the \@ sign, as in `@khaled2018`.
|
||||
1. To add parentheses to a reference use square brackets, as in `[@khaled2018]`
|
||||
2. For multiple citations, separate keys with semicolons, as in `@khaled2018;@graziano2019`
|
||||
3. To add a page or a note before or after a citation do `see @graziano2019 p.125`
|
||||
4. To export your reference collection, select the collection, right-click > Export Collection, select **Better BibLatex** (uncheck all options; background export optional):
|
||||
4. To export your reference collection, select the collection, right-click > Export Collection, select **Better BibLaTeX** (uncheck all options; background export optional):
|
||||
|
||||
3. Save your collection, e.g. as `mycollection.bib` . The resulting file is a set of citation keys, each with its own citation metadata (you can preview the file with a text editor).
|
||||
|
||||
Notes:
|
||||
- In case you modified your Zotero collection (included more items or edited existing itmes), re-export the collection and overwrite the previous `bib` file.
|
||||
- BibTex export format will omit URLs associated with an entry! *Opt for BibLaTex export format.*
|
||||
- The format of citation keys can be changed in the [Better Bibtex][] preferences (Zotero: Tools > Better BibTex > Open preferences). A minimal format is `auth.lower+year`.
|
||||
- In case you modified your Zotero collection (e.g. added/removed items or edited existing items), re-export the collection and overwrite the previous `bib` file.
|
||||
- *Opt for the BibLaTeX export format.* The BibTeX export format will omit URLs associated with an entry!
|
||||
- The format of citation keys can be changed in the [Better Bibtex][] preferences (Zotero: Tools > Better BibTex > Open preferences). The format used in this example is `auth.lower+year`.
|
||||
|
||||
|
||||
# Using citation keys in Markdown documents {#cite}
|
||||
|
||||
To add a citation in a Markdown file, just prefix a citation key (from Zotero) with the `@` sign, as in `@khaled2018`.
|
||||
|
||||
|
||||
|
||||
When the document will be compiled against a bibliography and a citation style, citation keys will be rendered according to the specified citation style *and* a reference will be added to the bibliography section for each citation.
|
||||
|
||||
For author-year type citation styles:
|
||||
- To add parentheses to a reference use square brackets, as in `[@khaled2018]` --> "(Khaled et al. 2018)")
|
||||
- For citing multiple sources at once separate keys with semicolons, as in `[@khaled2018;@graziano2019]` --> "(Khaled et al. 2018; Graziano et al. 2019)"
|
||||
- To supress the author name (in author-date citation styles) do `[-@khaled2018]` eg. "According to Khaled and colleagues [-@khaled2018]" will render as "According to Khaled and colleagues (2018)")
|
||||
- To add a page or a note before or after a citation do `[see @graziano2019, p.125]` --> (see Graziano et al. 2019, p.125)
|
||||
|
||||
|
||||
# Get a citation style file (CSL)
|
||||
|
||||
Download a citation style file (CSL), from [the official citation style repository](https://github.com/citation-style-language/styles) (GitHub repository), or from the [Zotero Style Repository](https://www.zotero.org/styles) (search interface).
|
||||
Use a provided citation style file (CSL), or download one from [the official citation style repository](https://github.com/citation-style-language/styles) (GitHub repository), or from the [Zotero Style Repository](https://www.zotero.org/styles) (search interface).
|
||||
|
||||
# Gather files
|
||||
Note: Zotero features a citation style editor (Tools > Style Editor), for modifying existing citation styles if needed.
|
||||
|
||||
[^dir]: An easy way to get the absolute path of a file, is to drag and drop a file into a terminal (e.g. *PowerShell* in Windows and *Terminal* in macOS). Select the path that will appear, and right click, copy.
|
||||
# Gather files and paths
|
||||
|
||||
- Optional good practices:
|
||||
- Gather your document, bibliography, and CSL files in the same directory, say `/mydocument/`.
|
||||
- Place images inside a subdirectory, e.g. `/mydocument/graphics/`
|
||||
- Make a subdirectory for exported documents e.g. `/mydocument/export/`
|
||||
- Avoid using spaces in directory or file names.
|
||||
- Make sure that images referenced in the Markdown document use a the correct file path.
|
||||
- Gather file paths for your MD, CSL, and BIB files.[^dir]
|
||||
- Markdown file:
|
||||
```
|
||||
"/path/to/my-article.md"
|
||||
```
|
||||
- Bibliography bib file:
|
||||
```
|
||||
"/path/to/mycollection.bib"
|
||||
```
|
||||
- Citation style file:
|
||||
```
|
||||
"/path/to/reference-style.csl"
|
||||
```
|
||||
The next step is to make a note of the paths of your Markdown document, citation style, and bibliography files, which will be used to compile a new document.
|
||||
In addition, make sure that the path of any image referenced in the Markdown document is correct.
|
||||
|
||||
Good practices:
|
||||
- Gather your Markdown document, bibliography, and CSL files in the same directory, e.g. `/mydocument/`.
|
||||
- Place images inside a subdirectory, e.g. `/mydocument/graphics/`
|
||||
- Make a subdirectory for exporting documents e.g. `/mydocument/export/`
|
||||
- Avoid using spaces in directory or file names.
|
||||
- It is recommended to write down these paths either in a comment section inside your document, or in a separate text file, as in:
|
||||
```
|
||||
<!-- Exporting notes
|
||||
|
||||
Markdown document (md):
|
||||
"/path/to/mydocument/my-article.md"
|
||||
|
||||
Bibliography file (bib):
|
||||
"/path/to/mydocument/mycollection.bib"
|
||||
|
||||
Citation style file (csl):
|
||||
"/path/to/mydocument/reference-style.csl"
|
||||
|
||||
Export directory:
|
||||
"/path/to/mydocument/export/"
|
||||
|
||||
[Here you can also assemble the pandoc command for converting this document (discussed in the next sections), so that it can be easily reused.]
|
||||
-->
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Enclosing file paths within "quotes" is optional. However, using paths inside quotes can bypass the need for special characters in case of spaces in file or directory names.
|
||||
- You can use both absolute paths to files, or relative paths. However, for relative paths, pandoc commands will need to be executed from the base directory that the relative paths.
|
||||
- File paths can be either absolute (e.g. `c:/users/me/some-folder/some-file.md`), or relative (e.g. `/some-folder/some-file.md`). However, for relative paths pandoc commands will need to be executed from the base directory of these relative paths.
|
||||
- An easy way to get the absolute path of a file or directory, is to drag and drop it into a terminal, then select the path that will appear, right click, and copy.
|
||||
- Enclosing file paths within "quotes" is optional. However, doing so can bypass the need for special characters in cases where file or directory names contain spaces.
|
||||
|
||||
# Test Pandoc and your Markdown document
|
||||
# Test Pandoc and the Markdown document
|
||||
|
||||
Open a terminal:
|
||||
- to test that [Pandoc][] works do:
|
||||
- to test that [Pandoc][] works do (if the `pandoc` command is not recognized as valid go to [installation instructions](#pandoc-install):
|
||||
```
|
||||
pandoc --version
|
||||
```
|
||||
- to test that your Markdown document is in order do (this will not compile the bibliography):
|
||||
```
|
||||
For docx export:
|
||||
pandoc "path/to/my-article.md" -o "/path/for/export.docx"
|
||||
pandoc "/path/to/mydocument/my-article.md" -o /path/to/mydocument/export/my-article.docx"
|
||||
|
||||
or for pdf export:
|
||||
pandoc "path/to/my-article.md" -o "/path/for/export.pdf"
|
||||
pandoc "/path/to/mydocument/my-article.md" -o "/path/to/mydocument/export/my-article.pdf"
|
||||
|
||||
or for Markdown export:
|
||||
pandoc "path/to/my-article.md" -o -o "/path/to/export-document.md" --atx-headers --strip-comments --wrap=preserve -t markdown_mmd-citations --standalone
|
||||
|
|
@ -121,6 +208,37 @@ To compile to DOCX using a DOCX document as reference/template add the option:
|
|||
|
||||
*Note: Conversions to *DOCX* format will use Footnotes, not Endnotes.*
|
||||
|
||||
|
||||
# Specify bibliography placement
|
||||
|
||||
By default, [pandoc][] will insert the bibliography at the end of the document. To force the bibliography to render at a specific location if needed -- for example before endnotes or appendix sections -- add the following to the target location for your bibliography:
|
||||
|
||||
```
|
||||
... article body ...
|
||||
|
||||
# Bibliography
|
||||
|
||||
::: {#refs}
|
||||
:::
|
||||
|
||||
# Some other appendix
|
||||
Lorem ipsum.
|
||||
|
||||
```
|
||||
|
||||
or
|
||||
```
|
||||
... article body ...
|
||||
|
||||
# Bibliography
|
||||
|
||||
<div id="refs"></div>
|
||||
|
||||
# Some other appendix
|
||||
Lorem ipsum.
|
||||
```
|
||||
|
||||
|
||||
# Common errors
|
||||
|
||||
- missing/wrong citation keys: [Pandoc][] will list all citation keys that were not found in the supplied `bib` file. Correct any potential citation key misspellings, or recompile your bibliography collection to include the missing citations.
|
||||
|
|
|
|||
|
|
@ -11,6 +11,7 @@ abstract: |
|
|||
Submission guide.
|
||||
---
|
||||
|
||||
A detailed submission guide can go here, or at .
|
||||
|
||||
<!--
|
||||
This journal is committed to the use of free and open source tools, workflows and platforms, for the production of open, accessible, and resilient knowledge.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ Sandpoints is developed for free, open, and collaborative publishing using open-
|
|||
Content is organized with plain-text Markdown files, and collaboration/version control is managed via [Git].
|
||||
Thus, with the infrastructure in place, no programming is needed.
|
||||
|
||||
However, for managing and maintaining the site in a sustainable manner, as well as for processing/publishing submissions, *some knowledge is required pertaining to how this infrastructure works and how it can be maintained; how to work with ; how to manage distributed collaboration via a version control system; and to adhere to agreed upon conventions.*
|
||||
However, for managing and maintaining the site in a sustainable manner, as well as for processing/publishing submissions, *some knowledge is required pertaining to how this infrastructure works and how it can be maintained; how to work with ; how to manage distributed collaboration via a version control system; and to adhere to agreed upon conventions.*
|
||||
|
||||
This is an internal 'issue' (supposed to remain non-public, intended as a 'living document'), which contains the following 'articles':
|
||||
|
||||
|
|
|
|||
|
|
@ -3,17 +3,30 @@ title: "Authors Submission Guide ⚫"
|
|||
date: "2023-07-14T20:25:33+03:00"
|
||||
author: "file-creator-put-your-name-here"
|
||||
draft: false
|
||||
has_articles: ["submission-guide.md", "md-workflow.md", "markdown-formatting.md", "sample-article.md" ]
|
||||
has_articles: ["submission-guide.md", "sample-article.md", "md-formatting.md","md-workflow.md", "ex-constantinos-digra-md.md", "ex-constantinos-digra-compiled.md" ]
|
||||
keywords:
|
||||
- draft
|
||||
- guide
|
||||
abstract: |
|
||||
The text of your abstract. (Below is an instruction checklist for issue-file creators/editors)
|
||||
This 'issue' contains information and submission guides for authors.
|
||||
---
|
||||
|
||||
- Mention of commitment/focus
|
||||
|
||||
ToDo:
|
||||
- Mention commitment/focus
|
||||
- Submit only in open calls, or any time
|
||||
- What is possible to submit
|
||||
- Submission template - 
|
||||
- Archiving of artifacts
|
||||
- Review process
|
||||
- Reviewer guidelines
|
||||
- Reviewer guidelines
|
||||
|
||||
|
||||
# Introduction
|
||||
|
||||
Contributions of this project are published in Markdown format.
|
||||
Submissions can be submitted either in Markdown, or in conventional word processor documents.
|
||||
|
||||
For Markdown submissions check the , and the .
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue