Make code blocks look more like Stata code

[arthur-shaw]

To my mind, this entails:

• Syntax highlighting
• Styling that makes code block look like Stata console/dofile editor

This might translate into a few tasks

• Mark code blocks as Stata--ideally when writing from md to qmd. See Quarto docs here.
• Apply a Stata-looking style. Either adopting a built-in style that's close or rolling our own. See Quarto docs here

[arthur-shaw]

For Stata-looking style, here are some (subjectively) good looking themes for Stata:

Need a YAML header like this for each:

---
highlight-style: atom-one
---

ayu-dark:

nord:

atom-one, which is adaptive

[arthur-shaw]

Note: there's a universal problem of highlighting Stata keywords as code even if they're behind comments. Might need a custom theme for this.

[kbjarkefur]

I use the keyword ```stata in the beginning of a code block. That seems to work. I have however, not built in support for this in ad_sthlp for when converting .mdhlp files to .sthlp. It is quite an easy fix, as all it needs is to test that the only thing coming after ``` is stata and then just disregard it as there is no syntax highlighting in sthlp.

It currently already works on README.md and on vignettes and I am already using it on in repkit. See for example this file: https://dime-worldbank.github.io/repkit/articles/ado-management-with-repado.html. Scroll down for some better examples.

[kbjarkefur]

Let me know if you see some reason for why ```stata is not sufficient.

[arthur-shaw]

For adding the language to the codeblock, we could also do this on the adodownr side.

However we do it, it seems like Stata keywords that appear after comments are still highlighted. Here's an example from repkit (next to last code block on the page you linked) :

If that's OK, we only need to say that these are Stata codeblocks.

If not, we might need to tweak the syntax highlighting tooling--perhaps making upstream changes to the tooling Quarto uses (e.g., Quarto highlights Stata via' Pandoc (see here); we could write a custom highlighter via skylighting (see here).

[arthur-shaw]

This turns out to be a Pandoc issue. I can replicate the behavior above with only Pandoc.

I'll raise an issue with Quarto, Pandoc, and/or skylighting, the library Quarto and Pandoc use for syntax highlighting.

I suspect

Steps to reproduce

1. Create a Markdown file named stata_test.md containing a Stata code block

---
title: Hello
---

Here's some Stata code:

```stata
* Set PLUS to adopath and list it first, then list BASE first.
* This means that BASE is first and PLUS is second.
adopath ++  "${root}/code/ado"
adopath ++  BASE
```

2. Build HTML file with Pandoc

pandoc stata_test.md -f markdown -t html -s -o stata_test.html

Result:

[arthur-shaw]

We can track things on this issue for skylighting, an upstream component of Pandoc/Quarto.