Add XDG support to key bindings, snippets, themes, and file templates #5144

jmcphers · 2019-07-25T22:27:26Z

This change continues the work started in #5069, continuing to further the 1.3 goal of (a) having all configuration data in a single, configurable folder and (b) supporting global customization of all settings.

Details

Prior to this change, these files were stored in hard-coded (and occasionally inconsistent) locations in the user's home dir:

Themes and keybindings were in ~/.R/rstudio
Snippets were just in ~/.R
File templates were in a built-in, read-only folder

Each of these has undergone similar work:

All of the resources are now stored in ~/.config/rstudio (configurable)
For interoperability with 1.2 and prior, we support both the old and new folders. If you have any of these resources in the legacy folder location, we will continue to read from that folder. However, new content you add will be only be placed in the new folder.
The system folder is now read in addition to the user folder, making all of these features admin-extensible (mostly for the first time). Merging or overriding is done as appropriate.

As an example, if a user has done some customization to RStudio, here's what their ~/.config/rstudio folder might look like: it contains their preferences, key bindings, snippets, templates, and themes, all in plain, user-friendly text files.

 .
├── keybindings
│   ├── addins.json
│   ├── editor_bindings.json
│   └── rstudio_bindings.json
├── rstudio-prefs.json
├── snippets
│   └── r.snippets
├── templates
│   ├── default.R
│   ├── default.Rmd
│   ├── default.cpp
│   ├── default.js
│   └── notebook.Rmd
└── themes
    └── Brogrammer.rstheme

Templates

The templates folder deserves some special mention since it was not previously customizable. You can now define the default content for any file type. For example, to set the default content for R scripts (what you see in the editor buffer when you click File -> New R Script), you can edit:

~/.config/rstudio/templates/default.R

Some file types, such as R Markdown, have non-default templates. These are also customizable via specially named files; for example default.Rmd sets the content for blank R Markdown documents, but notebook.Rmd sets the content for blank R Markdown notebooks.

The admin guide will document the full list of special templates.

kevinushey · 2019-07-25T22:38:41Z

The templates folder deserves some special mention since it was not previously customizable. You can now define the default content for any file type. For example, to set the default content for R scripts (what you see in the editor buffer when you click File -> New R Script), you can edit:
~/.config/rstudio/templates/default.R
Some file types, such as R Markdown, have non-default templates. These are also customizable via specially named files; for example default.Rmd sets the content for blank R Markdown documents, but notebook.Rmd sets the content for blank R Markdown notebooks.

YAGNI might apply, but what do you think about allowing for multiple user-defined templates for each filetype? For example, the user might want:

~/.config/rstudio/templates/R/shiny-template.R
~/.config/rstudio/templates/R/bookdown-template.R

Ie, different templates for different single-file purposes. For now we'd only accept one template, but some theoretical day in the future this would allow us to e.g. provide a list of templates for the user to choose from (e.g. New -> From Template...)

kevinushey · 2019-07-25T22:42:30Z

src/cpp/session/modules/SessionSnippets.cpp

+   // Add user snippets files
+   dirs.push_back(getSnippetsDir());
+
+   for (const auto snippetsDir: dirs)


nit: const auto&; prefer ref?

good idea, done!

jmcphers · 2019-07-25T22:42:50Z

but what do you think about allowing for multiple user-defined templates for each filetype?

I think people would find it useful, but I don't think we need to build it now as it'd be meaningless without the UI. Is there something in the existing design that you think precludes us from taking this approach in the future?

kevinushey · 2019-07-25T22:49:39Z

Is there something in the existing design that you think precludes us from taking this approach in the future?

I don't think so -- I guess at worst we might have to migrate the default template files into filetype-specific subfolders, but that wouldn't be too bad. (I just wanted to double-check that we're at least leaving that door open; not suggesting we should take that work on now)

kevinushey

LGTM!

jmcphers · 2019-07-25T22:52:03Z

we might have to migrate the default template files into filetype-specific subfolders

I don't think we'd even need to do that! The file extension is sufficient:

~/.config/rstudio/templates/shiny-template.R
~/.config/rstudio/templates/bookdown-template.R

MariaSemple

Looks good to me!

samgreenbergBTO · 2019-08-21T23:44:01Z

Running R Studio Version 1.3.391 on OSX, my ~/.config/rstudio folder only contains rstudio-prefs.json and /dictionaries. Any idea why I'm not seeing /templates?

gtritchie · 2019-08-22T00:20:55Z

Running R Studio Version 1.3.391 on OSX, my ~/.config/rstudio folder only contains rstudio-prefs.json and /dictionaries. Any idea why I'm not seeing /templates?

@jmcphers can confirm, but my understanding is that the templates folder doesn't exist unless you create it and add your own default file templates to it.

jmcphers · 2019-08-22T17:19:08Z

@samgreenbergBTO @gtritchie is correct. The ~/.config folder contains only your own content (no RStudio defaults), so you'll need to create the templates folder yourself if you want to try this out.

samgreenbergBTO · 2019-08-24T00:04:58Z

Ok, I got it working. It works for making a new R Notebook if the template is named default.Rmd or notebook.Rmd but doesn't seem to work for R Markdown. Not really a big problem since they're functionally identical but is there a specific name for markdown template? I tried markdown.Rmd.

jmcphers · 2019-08-26T16:28:49Z

It's document.Rmd. The complete list can be found in pre-release versions of the admin guide:

https://docs.rstudio.com/ide/server-pro/1.3.399-1/r-sessions.html#default-document-templates

samgreenbergBTO · 2019-08-26T18:17:23Z

Great, thank you! Very happy this feature was added.

samgreenbergBTO · 2019-08-26T20:33:51Z

@jmcphers OK one more thing. When I create a new R notebook it loads the template as is. When I create a new R markdown it asks for title and author but even if I leave those fields blank it generates a new empty header on top of my template. If I try to create an empty document it throws an error.

jmcphers · 2019-08-26T21:29:38Z

Yes, if you use the wizard it's going to generate a YAML header for you, so your template should not include its own YAML header. If you want to have a YAML template in your header, use default.Rmd and the new Empty Document link in the wizard.

If you're seeing an error when creating an empty doc, please file an issue here!

samgreenbergBTO · 2019-08-26T22:00:36Z

OK, when I go File > New File > R Markdown.. > Create Empty Document I get Error: No Such File or Directory

jmcphers added 7 commits Jul 24, 2019

read keybindings from XDG standard dirs

ad1d40d

read themes from XDG standard location

5a41792

allow for user and system configuration of templates

c371cf0

allow for creating empty R Markdown docs

e46ffee

add XDG support for snippets

a12f97b

use OSX variant of template if present (built-in only)

cd70c65

update comments

b06ec9e

jmcphers requested review from MariaSemple and kevinushey Jul 25, 2019

fix extraction of mode from system snippet configs

e198e50

kevinushey reviewed Jul 25, 2019

View changes

kevinushey approved these changes Jul 25, 2019

View changes

MariaSemple approved these changes Jul 26, 2019

View changes

prefer reference for iterator

7f9b21b

jmcphers merged commit df5267d into master Jul 26, 2019

jmcphers mentioned this pull request Jul 30, 2019

Spelling custom dictionary folder should conform to XDG standard #5162

Closed

jmcphers mentioned this pull request Aug 14, 2019

User and admin customizable default file templates #1632

Closed

valerie-rstudio deleted the feature/xdg-standardization branch Jan 21, 2022

Add XDG support to key bindings, snippets, themes, and file templates #5144

Add XDG support to key bindings, snippets, themes, and file templates #5144

jmcphers commented Jul 25, 2019

kevinushey commented Jul 25, 2019

kevinushey Jul 25, 2019

jmcphers Jul 26, 2019

jmcphers commented Jul 25, 2019

kevinushey commented Jul 25, 2019

kevinushey left a comment

jmcphers commented Jul 25, 2019

MariaSemple left a comment

samgreenbergBTO commented Aug 21, 2019

gtritchie commented Aug 22, 2019

jmcphers commented Aug 22, 2019

samgreenbergBTO commented Aug 24, 2019

jmcphers commented Aug 26, 2019

samgreenbergBTO commented Aug 26, 2019

samgreenbergBTO commented Aug 26, 2019 •

edited

jmcphers commented Aug 26, 2019

samgreenbergBTO commented Aug 26, 2019 •

edited

Add XDG support to key bindings, snippets, themes, and file templates #5144

Add XDG support to key bindings, snippets, themes, and file templates #5144

Conversation

jmcphers commented Jul 25, 2019

Details

Templates

kevinushey commented Jul 25, 2019

kevinushey Jul 25, 2019

Choose a reason for hiding this comment

jmcphers Jul 26, 2019

Choose a reason for hiding this comment

jmcphers commented Jul 25, 2019

kevinushey commented Jul 25, 2019

kevinushey left a comment

jmcphers commented Jul 25, 2019

MariaSemple left a comment

samgreenbergBTO commented Aug 21, 2019

gtritchie commented Aug 22, 2019

jmcphers commented Aug 22, 2019

samgreenbergBTO commented Aug 24, 2019

jmcphers commented Aug 26, 2019

samgreenbergBTO commented Aug 26, 2019

samgreenbergBTO commented Aug 26, 2019 • edited

jmcphers commented Aug 26, 2019

samgreenbergBTO commented Aug 26, 2019 • edited

samgreenbergBTO commented Aug 26, 2019 •

edited

samgreenbergBTO commented Aug 26, 2019 •

edited