Rstudio Markdown to Markua: A Leanpub Tale of Markdown Flavors

The Story

I wrote a markdown book on Programming and Digital Humanities. I learned how to use Rstudio and Rbookdown on the way, they made it super easy to write the book. So I ended up with an R Markdown file (.Rmd).

GitHub was the first choice to share it. It renders Markdown directly, but not .Rmd — Yuhui has a wonderful post on why .Rmd is not rendered as .md on GitHub. So I changed it to standard Markdown (.md). People can preview the book, something may get lost in translation, but having the stuff out was already cool.

I also thought that if you really really really want the book you can clone it, renamed as .Rmd as R build it.

Still, the book was not so user friendly for people in academia and humanities. Plus, it would be cool to have a tool to make the GitHub book an ebook that compiles on all formats. (I know more people that read ebooks than those that can clone and process .Rmd bookdown.)

Leanpub proves to be such a tool, but before reaching the goal there are more struggles with markdown flavors.

So here I am, transitioning the book into a new Markdown flavor, Markua.

Introducing Markua

Leanpub has its own version of markdown called Markua which works for courses and books you may display on their website. Specs are here in book format and here in their latest version.

When moving content across formats its good to know what features you are using, how they are supported in the current format, and how they are implemented in the target format. Basically, that was my path:

  1. find out what you need to render the book;
  2. find out how that’s done in Markua;
  3. if Markua’s way is different from Rmd, write a script to fix it for you;
  4. and be sure to test the stuff.

(If you are interested in further moving to Markua experience, here’s another take on that.)

#markua #leanpub #markdown #digital-humanities #python

What is GEEK

Buddha Community

Rstudio Markdown to Markua: A Leanpub Tale of Markdown Flavors

Rstudio Markdown to Markua: A Leanpub Tale of Markdown Flavors

The Story

I wrote a markdown book on Programming and Digital Humanities. I learned how to use Rstudio and Rbookdown on the way, they made it super easy to write the book. So I ended up with an R Markdown file (.Rmd).

GitHub was the first choice to share it. It renders Markdown directly, but not .Rmd — Yuhui has a wonderful post on why .Rmd is not rendered as .md on GitHub. So I changed it to standard Markdown (.md). People can preview the book, something may get lost in translation, but having the stuff out was already cool.

I also thought that if you really really really want the book you can clone it, renamed as .Rmd as R build it.

Still, the book was not so user friendly for people in academia and humanities. Plus, it would be cool to have a tool to make the GitHub book an ebook that compiles on all formats. (I know more people that read ebooks than those that can clone and process .Rmd bookdown.)

Leanpub proves to be such a tool, but before reaching the goal there are more struggles with markdown flavors.

So here I am, transitioning the book into a new Markdown flavor, Markua.

Introducing Markua

Leanpub has its own version of markdown called Markua which works for courses and books you may display on their website. Specs are here in book format and here in their latest version.

When moving content across formats its good to know what features you are using, how they are supported in the current format, and how they are implemented in the target format. Basically, that was my path:

  1. find out what you need to render the book;
  2. find out how that’s done in Markua;
  3. if Markua’s way is different from Rmd, write a script to fix it for you;
  4. and be sure to test the stuff.

(If you are interested in further moving to Markua experience, here’s another take on that.)

#markua #leanpub #markdown #digital-humanities #python

Nat  Grady

Nat Grady

1660994760

InsertImage: RStudio Addin for Inserting an Image Into Markdown

insertImage

R package: Insert image from file chooser into Markdown. Copy image to project. Addin for RStudio.

Inserts image code with alternative text specified by user in console.

If image file is not in the project (working directory or subdirectory) the user can copy the image file to the project. An img/ directory is created in the working directory, unless the document is in vignettes/ directory in which case the user can choose to copy to this directory instead.

Note: On Linux and possibly other OSes, if you are not asked whether to move an image that is not already in your working directory (or sub directory) to your working directory, it might help to set the working directory to the folder in which your active document exists.

By Ludvig R. Olsen, Cognitive Science, Aarhus University. Started in Feb. 2017

Contact at: r-pkgs@ludvigolsen.dk

Main functions:

  • insertImage

Installation

Development version:

install.packages("devtools")

devtools::install_github("LudvigOlsen/insertImage")

Use

  • Install package.
  • Add key command by going to:
    • Tools > Addins > Browse Addins > Keyboard Shortcuts.
    • Find Insert Image and press its field under Shortcut.
    • Press desired key command.
    • Press Apply.
    • Press Execute.
  • Press chosen key command inside R Markdown document.

Download Details:

Author: LudvigOlsen
Source Code: https://github.com/LudvigOlsen/insertImage 
License: View license

#r #markdown #image #rstudio 

Nat  Grady

Nat Grady

1661002500

Citr: RStudio Addin to insert Markdown Citations

citr: RStudio Addin to Insert Markdown Citations 

citr provides functions and an RStudio addin to search a BibTeX-file to create and insert formatted Markdown citations into the current document.

Installation

You can either use the stable version of citr from CRAN, Due to an intermittently orphaned dependency, citr is currently not on CRAN. Due to continuing SARS-CoV-2 related lockdowns, I'm having trouble allocating time to a resubmission. In the meantime, please install citr from this GitHub repository (see below).

# install.packages("citr")

or the current development snapshot from this GitHub repository:

devtools::install_github("crsh/citr")

How to use citr

The RStudio addin

Once citr is installed and you have restarted your R session, the addin appears in the menus. Alternatively, you can define a keyboard shortcut to call the addin.

addin_demo.gif

The addin will automatically look up the bibliography files specified in the YAML front matter. If the document does not contain a YAML front matter the addin will attempt to locate a parent document and look up the bibliography file specified therein. That is, the addin works its automagic even if you edit R Markdown documents that are included as children in another R Markdown document. The expected names of a parent document default to c("index.Rmd", "master.Rmd"), it thus works with bookdown out of the box, but can be customized (e.g., options(citr.parent_documents = "my_parent.Rmd")).

Using citr without RStudio

The following call searches a bibliography file and creates formatted Markdown citations for the results.

library("citr")
md_cite("foo 2016", bib_file = "references.bib")

md_cite() searches the author, year, title, and journal fields of your references.

Better BibTeX integration

If you are using Zotero citr can access your reference database directly. For this to work, you need to install the Better BibTeX extension. Once the extension is installed and your reference manager is running, citr can access all your references and keep your bibliography file updated by adding missing references.

addin_zotero_demo.gif

Tidying bibliography files

When you are done writing, your bibliography file is likely to contain some unneeded references, which you added while writing but removed during revisions. tidy_bib_file() removes unneeded (or duplicate) entries from your bibliography file.

tidy_bib_file(
  rmd_file = "report.Rmd"
  , messy_bibliography = "references.bib"
  , file = "tidy_references.bib"
)

Known problems

citr relies on RefManager::ReadBib() and, thus, indirectly on bibtex::read.bib() to load bibliographies. I have noticed that very long Bib(La)TeX fields can cause these underlying functions to fail (e.g., Error in do_read_bib(file, encoding = .Encoding, srcfile): lex fatal error: input buffer overflow, can't enlarge buffer because scanner uses REJECT). To avoid such problems, I strongly recommend to disable the export of potentially long metadata fields, such as abstract and notes. The Better BibTeX-plugin allows users to specify fields to omit:

Once, the above error has occurred, it may be necessary to restart the R session. Otherwise reading any other file may fail with Error: lex fatal error: fatal flex scanner internal error--end of buffer missed.

Other RStudio addins

If you are interested in other handy addins take a look at this list. There you can find other useful addins, such as rcrossref or wordcountaddin.

Package dependencies

Download Details:

Author: Crsh
Source Code: https://github.com/crsh/citr 
License: View license

#r #rstudio #markdown 

Nat  Grady

Nat Grady

1660898100

Remedy: RStudio Addins to Simplify Markdown Writing

remedy

{remedy} provides addins to facilitate writing in markdown with RStudio.

remedy_example.gif

All the functions are meant to be mapped to keyboard shortcuts. A list of suggested shortcuts is provided towards the end of this README.

Note that most of the addins/shortcuts below will also work without selecting any text.

Install

remotes::install_github("ThinkR-open/remedy")

Once you’ve installed the package, you don’t need to load it with library(), the addins are installed on your machine as part of the package install process.

Using {remedy}

Write quicker in markdown with {remedy}!
Read the full manual in the associated {pkgdown} website: https://thinkr-open.github.io/remedy/

Here’s a list of all available helpers:

remedy_example.gif

You can also have an overview of how the functions behave with the remedy_example() function:

library(remedy)
remedy_example( c("Never gonna", "give you up", "let you down"), listr )

Align

Align selected blocks to their assignment operator, either <-

align.gif

or =

alignequal.gif

Backtick

Enclose the selected word(s) in backticks.

backtick.gif

Blockquote

Turn selected line(s) to blockquote.

blockquote.gif

Chunk

Turn the selected text into a chunk.

chunk.gif

Note that every chunk is given a name.

chunksplit split the chunk at a given spot.

chunksplit.gif

Cross references

ID, table and figure cross-reference

cross-ref.gif

Emphasize

Embolden, italicize or strikethrough the selected text.

emphasise.gif

Footnotes

Turn the given text into a footnote.

footnote.gif

Headers

Turn the selected text into a header.

header.gif

HTML Comment

Turn the text into an html comment

htmlcomment.gif

Image

Turn the selected path into an image.

This element is context aware: if you select a text and a link, it turns the text into title between ![], and puts the link between ().

If the last element of the selection is not a link, you get an error message straight into you markdown document.

image.gif

LaTeX

LaTeX syntax :

latex.gif

List

Turn the selected text into an unordered list.

right.gif

Moving

On the right

Copy the selected text or the current line to the right.

right.gif

Table

Insert a table inside your doc.

There are basically two way to do that with remedy :

Ttable

table.gif

Parse your data

Turn your dataframe into a markdown table :

table_remedy.gif

URL

Turn the selected text into a link.

This element is context aware: if you select a text and a link, it turns the text into title between [], and puts the link between ().

If the last element of the selection is not a link, you get an error message straight into you markdown document.

url.gif

Youtube

Turn an url into a youtube embed:

youtube.gif

xaringan

Insert a xaringan pull-left and pull-right template.

xaringan.gif

Recommended shortcuts (macOS)

Here’s a list of recommended shortcuts:

remedy::remedy_opts$get('hotkeys')
#>           backtick               bold              chunk         chunksplit 
#>       "Ctrl+Cmd+`"       "Ctrl+Cmd+B"   "Ctrl+Alt+Cmd+C" "Ctrl+Shift+Alt+C" 
#>          chunkname           footnote                 h1                 h2 
#> "Ctrl+Shift+Alt+N" "Ctrl+Cmd+Shift+6"       "Ctrl+Cmd+1"       "Ctrl+Cmd+2" 
#>                 h3                 h4                 h5                 h6 
#>       "Ctrl+Cmd+3"       "Ctrl+Cmd+4"       "Ctrl+Cmd+5"       "Ctrl+Cmd+6" 
#>        htmlcomment              image            italics              latex 
#>       "Ctrl+Alt+C"       "Ctrl+Cmd+P"       "Ctrl+Cmd+I"       "Ctrl+Cmd+L" 
#>               list              right             strike              table 
#> "Ctrl+Shift+Cmd+="    "Alt+Cmd+Right"       "Ctrl+Cmd+S"       "Ctrl+Cmd+T" 
#>                url           xaringan            youtube 
#>       "Ctrl+Cmd+U"       "Ctrl+Cmd+X"       "Ctrl+Cmd+Y"

Managing Shortcuts

Use the {rsam} package to set and manage for you the hotkey settings of {remedy}.

If you want to edit the default settings you can view the defaults remedy_opts$get('hotkeys') and change them through remedy_opts$set(hotkeys=<NEW_SETTINGS>).

hotkeys <- remedy::remedy_opts$get("hotkeys")
rsam::set_shortcut(sprintf('remedy::%sr',names(hotkeys)), hotkeys)

Feedback and enhancement

You’ve found a bug, or have an enhancement idea? Feel free to open an issue : https://github.com/ThinkR-open/remedy/issues.

Code of conduct

Please note that the ‘remedy’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Download Details:

Author: ThinkR-open
Source Code: https://github.com/ThinkR-open/remedy 
License: View license

#r #hacktoberfest #rstudio #markdown 

Nat  Grady

Nat Grady

1660837320

SplitChunk: RStudio Addin for Splitting R Markdown Code Chunks

splitChunk

R package: Split code chunks in R Markdown. Addin for RStudio.

Inserts:

´´´

´´´{r}

By Ludvig R. Olsen, Cognitive Science, Aarhus University. Started in Feb. 2017

Contact at: r-pkgs@ludvigolsen.dk

Main functions:

  • splitChunk

Installation

Development version:

install.packages("devtools")

devtools::install_github("LudvigOlsen/splitChunk")

Use

  • Install package.
  • Add key command (e.g. mac: cmd-alt-shift-i, win: ctrl-alt-shift-i) by going to:
    • Tools > Addins > Browse Addins > Keyboard Shortcuts.
    • Find Split Code Chunk and press its field under Shortcut.
    • Press desired key command.
    • Press Apply.
    • Press Execute.
  • Press chosen key command inside an R Markdown code chunk.

Download Details:

Author: LudvigOlsen
Source Code: https://github.com/LudvigOlsen/splitChunk 
License: View license

#r #markdown #rstudio