Hello World! I’m back to blogging after a long hiatus of two whole years. People have been kindly asking how’s my life going. Since I haven’t written a blog post for so long, some people may be wondering if I quietly starved to death due to the lack of a full-time job, or just grabbed the 100 million dollars that the community donated to me in 2024 and retired to a tropical island.

Just kidding. I still live in Nebraska (although sometimes I do feel like being frozen to death—this week happens to be terribly cold). As a Nebraskan, I feel obliged to “support modern digital infrastructure” for my whole life because otherwise this XKCD cartoon would be a lot less fun:

Of course, I’m not really like the Nebraskan in the cartoon with that much burden on the shoulders, but I did have had two busy years. My sincere apologies for having not responded to your emails or messages yet—I got too many of them in January 2024 alone and was unable to catch up. I will try to reply to them gradually in the coming months this year. At least I have owed a lot of thanks to people who supported me in various ways over the past two years. Anyway, here is a public thank-you note to all my sponsors:

Thank you, sponsors!

I can’t express how much I appreciate your support! Although I sent a message to my Github sponsors on Feb 6, 2024 (and updated the blog post) telling them that the sponsorship would no longer be necessary, some generous friends still continued their sponsorship. In fact, 31 of them stayed all the way through this point.

Throughout January 2024, I kept getting Github notifications about new sponsors, and felt as if it were raining dollars to my house every day! I was totally unprepared to become the second richest man here in Omaha, Nebraska (watch out, Mr. Warren Buffett, I’m catching up!). Jokes aside, I am deeply touched by the outpouring of support from so many people around the world.

For the sake of transparency, I received about 30,000 USD in total from more than 300 sponsors in the past two years. Unfortunately, I thought the money could be treated as donation and hence not subject to income tax, but when filing taxes the next year, I realized it would be too complicated to provide proofs to IRS (I received the 1099-NEC form from Github), so I just let IRS eat a part of it (not sure how much because it was mixed with my other income). Anyway, with full gratitude in my heart, I donated and gave back about $15,000 from the remaining money to various open-source projects and individuals, among which 5000 euros went to the R Foundation.

What was even more valuable than the sponsorship money was the kind words and wishes under my previous post. I regard them as the most honorable award I have ever received in my life. Thank you all so much for letting me have an idea in advance what my funeral would be like! If I were a passer, I would have thought that the guy who wrote the blog post must have died…

Contract work

On the job side, I’ve been working as a contractor for Posit (continuing to maintain the R Markdown ecosystem), Swiss Re, and Merck.

George Bakoloukas from Swiss Re was the first to offer me a contract job after I announced my departure from Posit, and I’m very grateful for his trust and support. Working with Swiss Re has been a very valuable experience to me, because it was the first time that I have dipped my toes into the (insurance) industry as a software developer to watch closely how they use the tools developed by me and others. I worked purely on the tools side, not on actuarial or insurance modeling. One funny thing is that I went to college in 2002, aiming to become an actuary, but later I found this path was too hard for me after taking courses like insurance, accounting, actuarial mathematics, and interest theory, etc., and I finally switched to statistics…

I spent most of 2024 with Swiss Re, and in 2025 I started working with Merck primarily. It was also the first time that I had walked into the pharmaceutical industry. I’d like to thank Keaven Anderson and Nan Xiao from Merck for the quick rescue. I got the job in March 2024 but worked very lightly until 2025. Similarly, I worked on the tools side and don’t have much subject-matter knowledge about pharmaceuticals, but I have enough interesting things to keep me busy.

I really appreciate the flexibility and freedom offered to me by Posit, Swiss Re, and Merck. This year I might come back to a long-time interest of mine: (interactive) data visualization. It’s still at the prototype stage, so I can’t say much about it now.

Life

Before she can read, I want to take this opportunity to “blame” it on her for consuming so much of my time since May 2024. I can’t believe my third kid is 20 months old now, nor can I believe my oldest son is about to go to middle school. You can imagine what a blessing it is to have one kid kicking a soccer ball against the wall, one constantly asking you where his crayon or glue is (and you can’t just tell him to look at .libPaths() or try install.packages(c('crayon', 'glue'))), and one reaching and smashing your keyboard while you work from home.

Now I think you can forgive me for not having responded to your messages yet.

I only traveled three times in the two years. Once to UC Berkeley to give a talk, once to visit families in China, and once to New Zealand (for the first time) to give the Ihaka lecture. One most memorable moment was when I climbed to the top of the Maungawhau (Mt Eden) volcano in Auckland (in my flip-flops, as usual). I had known the vocalno dataset in base R for nearly 20 years, and finally I got to see the real volcano in person!

My limited spare time was mostly devoted to cooking, reading, gardening, and badminton. Occasionally I also do karaoke at home, and I think I have improved a little bit (although vibrato is still hard like hell for me).

A personal project

As indicated in my previous post, I wished to pursue minimalism further. Before my daughter was born, I spent about a month on writing a lightweight version of R Markdown called litedown almost from scratch. The goal was to get rid of many dependencies (including Pandoc and knitr), with a focus on HTML output. This was an interesting experiment, and meant to be my last “*down” package. I don’t expect it to be widely adopted, although it’s powerful enough to me and I’d like to call it nearly feature-complete. Unfortunately, I haven’t had enough time to finish the documentation.

What’s next?

Working as a contractor was quite challenging for me in the beginning, but I’ve adapted to it gradually and found the proper cadence. I like the flexibility it offers, despite the instability of income, which doesn’t bother me much (e.g., when I’m sick, I’ll be on my own since there is usually no paid “sick leave” for contractors, but I can work for extra hours if I really want to make it up, and I’ve never felt I need to). This year I’ll still be working primarily for Merck.

I have many topics on my mind for future blogging, and aim to write at least one post per week. If you have suggestions on the topics, I’m all ears.

To my Chinese blog readers: many of you must have known that I batch publish all my Chinese posts once in a long while, and the last time I published was 3.5 years ago. I haven’t written a single post since 2024 until last month, when I made a decision that may surprise you—I plan to write fiction for a few years. Specifically, I’ll write fictional letters. Each letter’s topic will be from a song, and I’ll publish my karaoke recording at the end of each letter. To be honest, this feels quite embarrassing to me when I came up with the idea, because I’m not really good at singing. Nonetheless, I still want to leave some vocal records in my blog. I believe that imperfection also has its value.

I have added a very subtle “Donate” button at the bottom of each post. If you don’t look carefully, it should be easy for you to miss it, which was a deliberate choice of mine. If any of my post or software package is helpful to you, you may click the button to make a donation. I have zero expectation on how much money I can get from it, but I just want to keep the channel open for those who wish to support me in this way. Some people have suggested that I set up a paid subscription service for my blog or a private newsletter, but I’d like to keep my writings completely open and don’t want to sell anything. I think voluntary donations would be a better way to go.

That said, I do have a vague idea about a paid service—humor as a service (HaaS), with a premise that “if you don’t laugh, it’s free”. I think I’m relatively good at generating fun, but I have no idea when I’ll have time to implement this idea...

Originally I planned to write this post on Jan 4 to mark the two-year anniversary, but my daughter kindly passed a certain virus to me from her daycare, and I had to postpone it. Then I thought I should finish this post on Jan 19—my grandma’s birthday (she passed away in 2003 and I wrote a short story in memory of her in 2022), but was again interrupted by other things.

Finally, here I am. Hello world! Happy new year, everyone!

淡淡的情感 / 有时候 / 却能绵绵 / 不绝不断

小美：

您好！第一次给您写信，好紧张哦，紧张得就像您真的能收到一样。首先抱歉我是用简体中文写的，不过现在简体正体之间的转换工具应该很多，就劳驾您自[…] https://yihui.org/cn/2026/01/heart-sea/

Oh my heart / would surely stay

艾琳娜：

布列瑟农主教座堂的钟声又在我身后响起：当……当……当……我厌烦那钟声，尽管人类对它感到着迷和膜拜。自从他们建了这座教堂，我的[…] https://yihui.org/cn/2026/01/bressanone/

怕镜花水月终于 / 来不及 / 去相遇

小蝶：

你已飞走了五亿年，不知现在飞到了哪个纪元？可曾见到我留给你的印在叠层石上的一片花瓣？

它大概几经沧海桑田后不知被深埋在这颗星球的哪个角落了吧。就算你看[…] https://yihui.org/cn/2026/01/cambrian/

满天 / 都是谁的眼泪 / 在飞

阿玫：

我想和你聊聊飞舞。这个词给我的第一反应是：漫天飞舞 / 一片荒芜 / 满眼风雪和眼泪都化做尘埃！不过今天我的心情没有这么摇滚。我只是想起来三件微小的旧事。

[…] https://yihui.org/cn/2026/01/flying-tears/

The printr (read “printer” or “print R”) package is a companion package to[…] https://yihui.org/printr/

The package Rd2roxygen helps R package developers who used to write R documentation in the raw[…] https://yihui.org/rd2roxygen/

After writing about 20 R packages, I found I had accumulated several utility functions that I used[…] https://yihui.org/xfun/

Who is down? Me. After more than 10 years at RStudio/Posit, the time has come for me to explore other opportunities. A little over two weeks ago, I was told that I was laid off and my last day would be 2023-12-31. Frankly speaking, I was quite surprised but only for a short moment. I fully respected Posit’s decision, and quickly accepted the conclusion that my contribution no longer deserved a full-time job here. The end of a relationship often does not imply anything wrong or a failure of either party. Instead, it can simply indicate a mismatch, which is normal. People just change. With these amazing years in mind, I left mostly with gratitude in my heart.

# number of days I worked at RStudio/Posit
as.Date('2023-12-31') - as.Date('2013-08-26') + 1

Anyway, I guess this news may surprise some people in the R community and bring up questions or puzzles, so I want to write a blog post to address a few potential questions. If you have more, please feel free to ask me either by comments below or by email.

Acknowledgments

Despite the separation, I hold and value a lot of good memories about RStudio, which I could easily expand into another lengthy blog post, but I will save it for now since I got sick last week and am still recovering. In short, I would like to thank JJ for offering me my first ever full-time job and trusting me for so many years. I thank Joe and Tareef for the long-time mentorship (as well as friendship, I should say). I thank Hadley particularly for the guidance on the bookdown project from 2015 to 2016. I cannot say how much I appreciate Christophe’s help over the years (even a few years before he joined RStudio).

Really, there are too many people that I want to thank in the past ten years. Okay, I will write another post on this in the future after I settle down. As always, I am deeply grateful to the entire R and open source community for their belief and investment in the tools that I have been fortunate to work on.

No, those R packages will not be orphaned

At Posit, I felt blessed to work with super talented and committed engineers, and I believe that our collective work (in particular, R Markdown) has helped make R and reproducible research more accessible to the community and hopefully to the world as a whole.

After my departure from Posit, we are not going to drop these efforts. Posit has generously provided funding for me to continue, as a contractor, to support and extend knitr, rmarkdown, and various packages in this ecosystem. I look forward to continuing my collaboration with the Posit team on our shared areas of interest.

So please do not panic—our existing R packages will still be maintained. The only exception is the DT package, which is not included in the contract, and Posit plans to find a new maintainer for it. Before that happens, I might still be able to help (time permitting), but I cannot promise.

A minimalist has been growing inside me

Over the past three years, I have spent more time thinking and exploring a different approach to building software that is more minimalist and handcrafted than the larger projects like Shiny and Quarto, on which Posit is currently focused. I have become more interested in developing smaller software tools that do fewer things.

To a large extent, I’m leaning towards the “Less is More” or “Worse is Better” philosophy, and I find stoicism and the wabi-sabi concept very appealing. I do not mean my choice is correct or better. All choices are about a series of tradeoffs. I just happen to find a certain choice fits me better. Will I stick to it forever? I do not know.

This philosophical change of mine is not only about software development, but also my daily life. As a result, many friends find it hard to understand me when I ask them not to bring anything but an empty stomach when visiting me—perhaps someone who has visited me before can confirm it in the comments below.

What’s next?

Since I’m no longer a Posit employee, I’m facing some uncertainties now. I need to learn and figure out a few things that are new to me before I can come back to work again. Hopefully this will not take more than a couple of weeks.

The contract work I mentioned above is not enough for me to make a living (well, definitely enough for this minimalist guy but not for the family), so I’m also looking for opportunities that will give me the freedom and flexibility to continue to contribute to the R ecosystem and open source in general. If anyone has a job opening or is interested in my skills, I will be happy to chat, and please feel free to email me.

For now, I have not decided yet whether I want to take a full-time job next or just take this chance to become an independent contractor. It depends on the opportunities that I can get in the next few months.

Update on 2024-03-19

Please ignore the call for help below, and feel free to cancel your monthly sponsorship. I no longer need financial aid. Currently I’m (busy) working for SwissRe as a contractor, and should have enough income this year. For the donations that I have received, I have been passing them to other people and organizations of my choice. If you have suggestions on where I should donate the money, I will be happy to follow your advice. Many thanks to everyone who lent a helping hand to me! Please also feel free to let me know if you need help or know someone else who needs help (e.g., with seeking for job opportunities).

I have never asked for financial support from the community before, because I have never felt the need (thanks to Posit). Now the situation has become different, and I’m a little concerned about the mortgage number in my account. For the first time, I’m mentioning my GitHub sponsorship page in my blog: https://github.com/sponsors/yihui. I will be very grateful if anyone could support me for a few months before I transition into the next stable phase of life. I will notify you when I do not need the sponsorship any more so you can cancel it if you are on a monthly tier. I will be happy to offer some casual help in return just as tiny side jobs. For example:

• Answer your questions (technical or non-technical);

• Help you optimize your website, or more importantly, cultivate a habit of writing so you can keep writing for the years to come;

• Advise on how to make your presentation entertaining (but I refuse to sell my precious 20-year old GIF collections);

• Share my experience on cooking, gardening, badminton, or even setting up a simple Karaoke system at home (now you are highly skeptical if this so-called minimalist gentleman is genuine);

• As a “down” expert, write a letter to cheer you up if you are down for some reason (since the pandemic, I seem to have become much better at writing letters).

We don’t say goodbye. So actually this is not a “bye” to anyone, but a “hi” to an unknown new journey. I have enjoyed the past decade, and I’m in full curiosity about the future.

Three years ago, Xianying Tan helped me add the SearchBuilder extension of DataTables to the DT package. This extension did not exist when I first started developing DT, otherwise I would not have spent countless hours on creating a variety of filters in DT by myself and make them work in both the client and server modes. This extension is much, much more flexible than my clumsy “homemade” filters.

Yes, SearchBuilder has been made available to DT three years ago, but the problem is that it only works on the client side. That is, if you render a table in Shiny, you cannot DT::renderDT(server = TRUE) and can only do server = FALSE. The filtering logic is not implemented on the server side.

Users have been asking how to make it work in the server mode, and one asked again last week. Unfortunately I do not really have time for this task, but I think it is an interesting little project, so I’m sharing tips on how it could be possibly implemented, in the hope that someone could pick it up and get it done. I do not think it is technically hard, but it definitely requires some focus time.

Basically, you need to inspect the object q during debugging the internal function DT:::dataTablesFilter, and you will see parameters sent from SearchBuilder in q$searchBuilder. You need to implement the filters by dealing with these parameters with R code. Here is how you can get started:

debug(DT:::dataTablesFilter)

library(shiny)
shinyApp(
  fluidPage(DT::DTOutput('foo')),
  function(input, output) {
    output$foo = DT::renderDT(
      data.frame(
        a = sample(26), b = letters,
        c = factor(rep(c('a', 'b'), 13)),
        d = Sys.Date() + 1:26,
        e = Sys.time() + 1000 * (1:26)
      ),
      options = list(dom = 'Qlfrtip'),
      extensions = c('SearchBuilder', 'DateTime')
    )
  }
)

In DT:::dataTablesFilter, you can see how I implemented searching, pagination, and sorting with R code. Similar things need to be done for parameters in q$searchBuilder.

Please let me know if you need more guidance. I’m sure at least a few users will be grateful if this could be done, and so will I.

Since about a month ago, I have been receiving error reports from TinyTeX users saying “TinyTeX\bin\windows\runscript.tlu:864: no appropriate script or program found: fmtutil” or “I can't find the format file `pdflatex.fmt'!”, which I do not understand.

For the last few days, I scratched my head, banged against the wall, did some research, asked R and LaTeX experts in mailing lists, got reminded of “[[alternative HTML version deleted]]” again (and apologized, of course), dug out an old Windows laptop, proudly created a new user account with my authentic Chinese name for the first time of my life (instead of using Pinyin), went through trial and error, learned a variety of bizarreness of Windows batch scripts as well as the Stack Overflow cures, summoned all Chinese students in my alma mater to test their own Windows machines and the Windows servers in their department, and meditated on the meaning of life for three seconds. Finally I’m happy to announce that I have found a fix and applied it to tinytex (the R package) v0.49.

TLDR; The fix

If you have run into the above errors when rendering R Markdown or Quarto or LaTeX documents to PDF, you can install the latest version of tinytex from CRAN:

install.packages('tinytex')

Please remember to restart R after installation. Then make sure packageVersion('tinytex') >= '0.49').

The problem

If your Windows username does not contain spaces or non-ASCII characters, this problem should not affect you.

Sys.getenv('APPDATA')
xfun::is_ascii(.Last.value) && !grepl(' ', .Last.value)

Although I have used LaTeX for nearly two decades, I have learned for the first time (from Akira Kakuto) that TeX Live does not work on Windows when its installation path contains non-ASCII characters. By default, TinyTeX is installed to the path defined by the environment variable APPDATA, which is of the form C:\Users\username\AppData\Roaming. The problem comes from the username in this path, which can contain multibyte characters, and cause TeX Live to fail with a lot of error messages like below:

! warning: kpathsea: configuration file texmf.cnf not found in these directories: 
....
! ...s\username\AppData\Roaming\TinyTeX\bin\windows\runscript.tlu:941: ...s\username\AppData\Roaming\TinyTeX\bin\windows\runscript.tlu:864: no appropriate script or program found: fmtutil
! Running the command C:\Users\username\AppData\Roaming\TinyTeX\bin\windows\fmtutil-user.exe

! kpathsea: Running mktexfmt pdflatex.fmt

! The command name is C:\Users\username\AppData\Roaming\TinyTeX\bin\windows\mktexfmt

In theory, username containing spaces should be fine, because a space is an ASCII character. However, I have received reports that spaces can be trouble, too. I do know why (is this recent bug fix in base R relevant?).

The change

With tinytex v0.49, when your APPDATA path contains spaces or non-ASCII characters:

• If you run tinytex::install_tinytex() to install TinyTeX for the first time on a computer, it will install TinyTeX to the path defined by the environment variable ProgramData, which is typically C:\ProgramData. This path has no spaces or non-ASCII characters, but note that it is hidden by default (which is harmless). In addition, this folder is shared by all users in the system. If you have multiple users, this could be a problem. For example, other users can change or override your installation. If this is a concern, you can specify a different path via the dir argument of install_tinytex(). Remember this path should not contain special characters, either.

• If TinyTeX has already been installed to APPDATA, you will get a warning message telling you how to move it to ProgramData (you can also move it to another place if you want—just specify a different path to the to argument below). You may have to restart R or even the system after moving TinyTeX.

tinytex::copy_tinytex(to = Sys.getenv('ProgramData'), move = TRUE)

The installation script install-bin-windows.bat has also been updated accordingly.

A potential flaw

The above fix is based on the assumption that ProgramData is writable, which appears to be true according to various tests that I asked for from some students. If it is not true, you will have to specify your own installation path in tinytex::install_tinytex(), or if you use the Windows batch file, you can set the environment variable TINYTEX_DIR (which defaults to APPDATA or ProgramData).

Quarto users

The command quarto install tinytex is also impacted by this problem on Windows, and I have submitted a similar fix to Quarto. Before it is applied, moving TinyTeX by yourself can also fix the problem. The only issue is that for non-R users, there is not an automatic solution like calling an R function, and you will have to move it manually (then run tlmgr path add and also tlmgr postaction install script xetex if you use XeLaTeX).

If any Windows users run into any issues when installing or moving TinyTeX to the ProgramData folder, please feel free to let me know. Thanks!

When I suggested a department chair in 2019 that they may consider opening a blog so that all students and faculty in the department can write together (which sounded exciting to me), he expressed a concern that some readers might remember authors’ mistakes in the posts. Considering the reputation of the whole department, that is a valid concern. However, to err is human (and to forgive is divine). Everyone makes mistakes. I often update my old posts to correct mistakes or write a note saying certain information is oudated after a few years.

My notes did not have a formal form. Sometimes a note may be a blockquote, and sometimes it is just a normal paragraph. Today I was thinking how I could make them more consistent. One constraint is that it would be nice if I could express it in pure Markdown. Unfortunately, CommonMark does not support fenced Divs, otherwise I would use a fenced Div like:

::: Note
This post is outdated. Please ignore it.
:::

Eventually I decided to hack at definition lists. A note will be like:

Update on 2023-11-09

:   Please ignore this post. The method no longer works.

This will render to the HTML tag <dl> (with <dt> and <dd> inside).

Next I started to think about styling, and recalled the <fieldset> tag that I learned sixteen years ago.¹ With a few lines of JavaScript, I was able to change <dl> to <fieldset>. Below is a demo:

Notice on 2023-11-07

Thank you for noticing this new notice!

Your noticing it has been noted, and will be reported to the authorities.

If you want to use my JS code, you can load it via:

<script src="https://cdn.jsdelivr.net/npm/@xiee/utils/js/dl-fieldset.min.js" defer></script>

Then you only need to write Markdown:

Title

:   Content

which will be rendered to HTML:

<dl>
  <dt>Title</dt>
  <dd>Content</dd>
</dl>

Then my JS code will convert it to:

<fieldset>
  <legend>Title</legend>
  Content
</fieldset>

Mission complete.

Update on 2024-10-09

The markdown package has been superseded by the litedown package. The former is a strict subset of the latter. Please consider using litedown instead.

When we say “R Markdown”, we usually refer to the rmarkdown package, which is based on Pandoc and knitr. Prior to the rmarkdown package, there actually existed an older version of R Markdown, which was based on the markdown package instead of Pandoc. Later we called this version “R Markdown v1”.

R Markdown v1 was more or less an experiment, although many people liked it (perhaps because they had suffered for too long from LaTeX). It did not take long before we started developing v2, i.e., rmarkdown. V1 was much less powerful than v2. For example, it only supported HTML output but not LaTeX or any other output format. The now widespread CommonMark specs did not exist at that time, so v1’s Markdown syntax was chaos just like pretty much any other Markdown conversion tools (each having its own homemade or wild-caught specs) except Pandoc.

After R Markdown v2 became mature, v1 did not seem to be of much value any more. Perhaps it would just quietly fade out and eventually die. But…

But Jeroen Ooms, the great ninja, created the R package commonmark later. That changed the destiny of the markdown package. Previously, markdown was based on a C library, which had been deprecated for a long time. Last year, I removed the C library from markdown, and rewrote the package based on commonmark.

Although I’m a minimalist, commonmark’s Markdown features are too limited in my eyes. On the other hand, Pandoc’s Markdown is too rich to me. What I did in the markdown package was a compromise. You can read this chapter to learn which features are supported in this package.

If you prefer reading slides over documentation, I have given a talk in May, which was not recorded but you will not miss anything by only reading the slides.

This post is not meant to encourage people to use R Markdown v1. On the contrary, I think v2 and Quarto are better choices for most people. I just want to mention the revived markdown package, and there is a small chance that it actually meets some people’s need.

Declaring “feature complete” is hard, and it is definitely not a firm rejection to all future feature requests. It only means that “being feature-rich” is not the goal of this package. In particular, new features that require substantial work are unlikely to be added. Please feel free to request new features without a high expectation that they would be implemented.

P.S. Currently, the markdown repo is the only GitHub repo that I maintain and has zero open issues. For years, I thought Will Landau was the only person on earth who could possibly achieve this.

A couple of weeks ago I wrote about a lightweight HTML presentation format, snap slides. Today I want to briefly introduce a simple and lightweight HTML article format. You can find an example page here, which is also its documentation. You can generate an article like this with either the R package litedown or Quarto or any other tool that can generate HTML output. Under the hood, this article format is based on CSS and JS, which can be reused on any web pages.

If you use R Markdown or plain Markdown, you can install.packages('litedown') and specify the output format:

output:
  litedown::html_format:
    meta:
      css: ["default", "@article"]
      js: ["@sidenotes", "@appendix"]

If you use Quarto, you can also include the relevant CSS and JS:

format:
  html:
    minimal: true
    toc: true
    include-after-body:
      text: |
        <script src="https://cdn.jsdelivr.net/npm/@xiee/utils/js/sidenotes.min.js" defer></script>
        <script src="https://cdn.jsdelivr.net/npm/@xiee/utils/js/appendix.min.js" defer></script>
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@xiee/utils/css/default.min.css">
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@xiee/utils/css/article.min.css">
        <style type="text/css">header{text-align: center;}</style>

If you use other HTML generators, you can reuse the HTML code in the above Quarto example (in the text field).

The main features of this article format are: side elements (TOC, footnotes, sidenotes, and references), full-width elements, floating quotes, margin embedding, and appendices. Again, you can read its documentation to know more.

As I wrote last month, code folding was the most requested feature in blogdown, of which I have given an implementation. Today I will demonstrate an implementation of another top requested feature: tabsets.

How a tabset works

The mechanism of tabsets is fairly simple. It boils down to a click event on a tab link, which triggers the display of a corresponding tab pane. The user interface in HTML is like this:

<div class="tabset">
  <div class="tab-link">Tab 1</div>
  <div class="tab-link">Tab 2</div>

  <div class="tab-pane">Pane 1</div>
  <div class="tab-pane">Pane 2</div>
</div>

If the first tab link is clicked, we can add a class, say, active, to both the first link and the first pane.

  <div class="tab-link active">Tab 1</div>
  <div class="tab-pane active">Pane 1</div>

With some simple CSS, we can control the visibility of panes, and style the clicked link differently, e.g.,

.tab-pane {
  display: none;
}
.tab-pane.active {
  display: block;
}
.tab-link.active {
  border: 1px solid;
}

My implementation

There are several existing implementations of tabsets (e.g., in Bootstrap). The problem is that they are usually not tailored to Markdown users, and you have to prepare the appropriate HTML code by yourself. I have done an implementation today that works for both Markdown and HTML users.

You can find the source code tabsets.js and tabsets.css in my GitHub repo misc.js. For users, you certainly do not need to read the source, but can use it directly:

<script src="https://cdn.jsdelivr.net/npm/@xiee/utils/js/tabsets.min.js" defer></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@xiee/utils/css/tabsets.min.css">

If you are not satisfied with the styling, you can provide your own CSS and do not have to use my CSS.

Demo tabs

Below is an example tabset.

First tab

Hello world! Ciao!

Second tab

Here is a table.

More text.

A level-4 heading

Third tab

Nested tabs!

Tab 1

Isn’t it cool? Keep going!

Tab 2

Where am I now?

You can also create a tabset using raw HTML:

You can keep nesting but I’ll stop here.

Fourth tab

Enough tabs? Let me show a tabset created from a bullet list instead of section headings:

• First bullet

  Hi, bullet!

• Second bullet

  This is the initial active tab.

• Third bullet

  Bye, bullet!

Okay, I’m done now.

Documentation

HTML users

If you know HTML and prefer writing HTML, the required DOM structure has been mentioned in the first section of this post. Basically, you provide a container element with the class tabset (it does not have to be a <div>). Inside the container, you have a number of elements with the class tab-link, and the same number of elements with the class tab-pane.

When the i-th link is clicked, the i-th pane will be shown. You can set a certain tab link to be active initially by adding the class active to its HTML tag.

Note that you can have nested tabsets, e.g., a tabset inside a tab pane of a parent tabset.

Markdown users

If you prefer writing Markdown to be rendered to HTML by other tools (e.g., Hugo or the R package markdown), here is how you create a tabset:

1. Start with an element with the class tabset. This can be any type of element. For example, a heading:

   ## Demo tabs {.tabset}
   

   or an empty <div>:

   <div class="tabset"></div>
   

   You can also use a fenced Div with the class tabset:

   ::: tabset
   :::
   

2. Below this element, write either a bullet list or a series of sections.

   • If you write a bullet list, the first element of each bullet item will become the tab link, and the rest of elements will become the tab pane, e.g.,

     * Tab one
     
       Content of tab one.
     
     * Tab two <!--active-->
     
       Content of tab two.
     

     I’d recommend this method since it is easier and more natural to create a tabset. However, please make sure to indent the tab pane content properly in the bullet list (using the visual mode to write Markdown in RStudio can help a lot).

     To specify an initial active tab, add a comment <!--active--> to the bullet item.

   • If you write sections, the first section heading level will be the level of headings to be converted to tabs, e.g.,

     ### First tab (level-3)
     
     Some tab content.
     
     ### Second tab
     
     More tab content.
     
     #### A normal heading
     
     This is a level-4 heading, so it will *not* be
     converted to a tab.
     

     You can set a certain tab to be active initially by adding the class active to the heading, e.g.,

     ### Second tab {.active}
     

     One downside of using section headings to create a tabset is that the headings may be included in the table of contents of a page, which is why I do not recommend this method.

3. If you use sections to create a tabset, there are two ways to end the tabset (if you create a tabset with a bullet list, you do not need a special way to end it—it just ends where the list ends):

   1. Either start a upper-level heading (e.g., level 2 for the previous example), e.g.,

      ## My tabs {.tabset}
      
      ### Tab one
      
      ### Tab two
      
      ## A new level-2 section
      
      The previous tabset will be ended before this section.
      

   2. or write an HTML comment of the form <!-- tabset:ID -->, where ID is the ID of the element in Step #1, e.g.,

      ## My tabs {.tabset #my-tabs}
      
      ...
      
      <!-- tabset:my-tabs -->
      
      The previous tabset will be ended before this comment.
      

You can nest tabsets in other tabsets if you want, e.g.,

<div class="tabset"></div>

- Tab one

  Content

- Tab two

  Content

  <div class="tabset"></div>

    - Child tab one

      Content

    - Child tab two

      Content

- Tab three

If you use bullet lists to create tabsets, you can also put the list items inside the tabset div, which may be more intuitive, e.g.,

:::: tabset
-   Tab one

    Content

-   Tab two

    Content

    ::: tabset
    -   Child tab one

        Content

    -   Child tab two

        Content
    :::

-   Tab three
::::

I hope you can find this simple tabset implementation useful (it is not tied to blogdown or Hugo). Please feel free to let me know if you have any suggestions or comments.

I just finished reviewing a pull request in the knitr repo that tries to improve the error message when it fails to parse YAML, and I feel three base R functions are worth mentioning to more R users. I have been inspired by Maëlle Salmon’s 3 functions blog series, and finally started writing one by myself.

regexec(): get substrings with patterns

If you want to master string processing using regular expressions (regex) with base R, the two help pages ?grep and ?regexp are pretty much all you need. Although I had read them many times in the past, I did not discover regexec() until about three years ago, while this function was first introduced in R 2.14.0 (2011-10-31).

This function gives you the positions of substring groups captured by your regular expressions. It will be much easier to understand if you actually get the substrings instead of their positions, which can be done via regmatches(), another indispensable function when you work with functions like regexec() and regexpr(). For example:

x = 'abbbbcdefg'
m = regexec('a(b+)', x)  # positions
regmatches(x, m)  # substrings

[[1]]
[1] "abbbb" "bbbb"

The length of the returned value depends on how many () groups you have in the regular expression. In the above example, the first value is the whole match (abbbb is matched by a(b+)), and the second value is for the first group (b+) (any number of consecutive b’s).

If you do not know regexec() or regmatches(), it is natural to do substr() like the aforementioned pull request originally did:

message = e$message
regex = "line (?<line>\\d+), column (?<column>\\d+)"
regex_result = regexpr(regex, message, perl = TRUE)
starts = attr(regex_result, "capture.start")
lengths = attr(regex_result, "capture.length")
line_index = substr(message, starts[,"line"], starts[,"line"] + lengths[,"line"] - 1)
column_index = substr(message, starts[,"column"], starts[,"column"] + lengths[,"column"] - 1)
line_index = as.integer(line_index)
column_index = as.integer(column_index)

Its goal is to extract a line and column number from a string of the form "line x, column y". I rewrote the code (using my obnoxious one-letter-variable-name style) as:

x = e$message
r = "line (?<row>\\d+), column (?<col>\\d+)"
m = regmatches(x, regexec(r, x, perl = TRUE))[[1]][-1]
row = as.integer(m['row'])
col = as.integer(m['col'])

Note that (<?NAME>...) means a named capture, so you could later extract the substrings by names instead of numeric indices, e.g., m['row'] instead of m[1]. But this is not important. It is okay to use a numeric index.

BTW, if you are new to regular expressions and not sure if you should use perl = TRUE or FALSE (often the default) in the regex family of functions, I’d recommend perl = TRUE. Perl-compatible regular expressions (PCRE) should cause you fewer surprises and are more powerful.

strrep(): repeat a string for a number of times

How many times have you done this?

paste(rep('abc', 10), collapse = '')

I have done it for numerous times. Now, no more rep() or paste(). Use strrep() instead:

strrep('abc', 10)

It is even vectorized like most other base R functions, e.g.,

strrep(c('abc', 'defg'), c(3, 4))

I do not want to pretend that I have always known everything—in fact, I did not discover this function until about two years ago.

It is common to generate N spaces like the original pull request did:

spaces = paste(rep(" ", column_index), collapse = "")
cursor = paste(spaces, "^~~~~~", collapse = "")

And I rewrote it as:

cursor = paste0(strrep(" ", col), "^~~~~~")

append(): insert elements to a vector

Maëlle has mentioned append() in her post. Interestingly, it could be used in this pull request, too. Original code:

split_indexes = seq_along(meta) <= line_index
before_cursor = meta[split_indexes]
after_cursor = meta[!split_indexes]
error_message = c(
  "Failed to parse YAML: ", e$message, "\n",
  before_cursor,
  cursor,
  after_cursor
)

New code:

x = c("Failed to parse YAML: ", x, "\n", append(meta, cursor, row))

I remember when I first learned S-Plus in 2004, I was surprised to see a classmate wrote a t.test() function by herself (which was actually cool) and she was equally surprised when I told her that there was a built-in t.test() function. I think similar things still happen today. If you are not aware of regexec(), strrep(), or append(), it is easy and tempting to reinvent them, which can make your code lengthy and complicated.