Skip to content

Use console and Rconsole fenced code blocks for input/output examples #232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Use console and Rconsole fenced code blocks for input/output examples #232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
97e47b6
Use console and Rconsole fenced code blocks for input/output examples…
avinab-neogy Jun 13, 2025
07d3736
add custom CSS for console blocks
hturner Jun 17, 2025
4ba7f56
add customs CSS file
hturner Jun 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/build-mkdocs-website.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ on:

permissions:
contents: write

jobs:
build-and-deploy:
if: |
Expand Down
14 changes: 8 additions & 6 deletions docs/container_setup/local_setup/localsetup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,15 @@ systemctl start docker
in Dev Container. Click on `Reopen in DevContainer` button. ![start
localsetup](../../assets/rdev13.png)

7. After clicking on that button we will see our container is getting ready. It
7. After clicking on that button we will see our container is getting
ready. It
will take some time. So till that time you can have coffee :) ![start
localsetup](../../assets/rdev24.png)
8. We can also test whether the dev container is working or not by just printing
the environment variables mentioned in the welcome message on the terminal. And
there we go!!! We have setup our R Dev Container locally. ![start
localsetup](../../assets/rdev25.png)
the environment variables mentioned in the welcome message on the
terminal. And there we go!!! We have setup our R Dev Container locally.

9. The container will be closed when you close VSCode. To reopen the container,
open the `r-dev-env` directory in VSCode.
Comment on lines +61 to -64
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would put the new code block after the first sentence in step 8 and before "And there we go!!!".

Step 9 (deleted lines 63 and 64) should not have been deleted.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this might have gotten deleted after running the linter is what Im thinking
will correct this.

```console
$ echo $BUILDDIR
/workspaces/r-dev-env/bin/R
```
Comment on lines +63 to +66
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The old screenshot showed both input and output in the bash terminal, so you should use a console block rather than a bash block, and include both the bash command and the output (in future cases you may need to work through the tutorial to get the correct output!). Don't forget to prefix bash commands with the command prompt $ (ideally we could use /workspaces/r-dev-env (devel) $ as the full prompt, but the syntax highlighter then gets confused with bash commands that include dollar signs, so stick with a simple $ prompt).

The syntax highlighting we get with the Material theme doesn't look very different for console blocks, so I have committed some custom CSS to style the input differently from the output (input is black, output is grey) and to make the prompt symbol clearer (coloured blue). For inputs, I have applied the same styling to bash blocks, for consistency.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In case it is unclear - I corrected lines 63 - 66 when adding the custom CSS, so the code block is now correct, it just needs moving.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you Heather, I understand what you mean!

37 changes: 37 additions & 0 deletions docs/css/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
/* customise CSS for bash code chunks and bash sessions ("console") */

/* .gp = Generic Prompt (e.g., shell prompt like $ or >) */
/* default: var(--md-code-hl-generic-color); */
/* prompts treated as normal code in bash code chunks */
.language-console.highlight code span.gp{
color: #7aa2cd;
}

/* .go = Generic output: output from a command */
/* default: var(--md-code-hl-generic-color); */
.language-console.highlight code span.go,
.language-bash.highlight code span.go {
color: var(--md-code-hl-generic-color);
}

/* .nb = Built-in name like print, echo */
/* default: var(--md-code-hl-constant-color); */
.language-console.highlight code span.nb,
.language-bash.highlight code span.nb {
color: var(--md-code-hl-constant-color);
}

/* .nv = Named variables like $BUILDDIR */
/* default: var(--md-code-hl-variable-color); */
/* use same as normal text: var(--md-code-fg-color); */
.language-console.highlight code span.nv,
.language-bash.highlight code span.nv {
color: var(--md-code-fg-color);
}

/* .c1 = Built-in name like print, echo */
/* default: var(--md-code-hl-comment-color); */
.language-console.highlight code span.c1,
.language-bash.highlight code span.c1 {
color: var(--md-code-hl-comment-color);
}
4 changes: 4 additions & 0 deletions docs/tutorials/running_r.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,7 @@ VSCode window.
send code from the `.R` file to the R terminal by pressing `cmd/ctrl + enter`.

![alt text](../assets/rdev12.png) ![alt text](../assets/rdev5.png)

```Rconsole
hist(rnorm(1000))
```
Comment on lines +22 to +24
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rconsole blocks are for displaying input and output in an R session, similar to console blocks for sessions in a bash terminal. You need to include the prompt for input lines so that syntax highlighting is applied, i.e.

> hist(rnorm(1000))

However, an Rconsole block is not suitable in the case. The screenshot is intended to show the R script file, the hist(rnorm(1000)) command sent to the R terminal and the histogram in the plot window. Unfortunately, the screenshot here is wrong, it shows source("/workspaces/r-dev-env/R/test.R", encoding = "UTF-8"), which is the result of running Cmd/Ctrl + Shift + s not Cmd/Ctrl + enter, which is the short-cut we wish to document. You could fix this at the same time as the code fencing or open a separate issue about this.

5 changes: 5 additions & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,9 @@ theme:
primary: indigo
accent: blue

extra_css:
- css/custom.css

plugins:
- social
- search
Expand All @@ -70,6 +73,8 @@ extra:

markdown_extensions:
- pymdownx.highlight:
use_pygments: true
pygments_lang_class: true
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
Expand Down