Type: Package
Title: R Wrapper for 'pikchr' (PIC) Diagram Language
Version: 1.1.0
Date: 2026-04-07
Description: An 'R' interface to 'pikchr' (https://pikchr.org, pronounced "picture"), a 'PIC'-like markup language for creating diagrams within technical documentation. Originally developed by Brian Kernighan, 'PIC' has been adapted into 'pikchr' by D. Richard Hipp, the creator of 'SQLite'. 'pikchr' is designed to be embedded in fenced code blocks of Markdown or other documentation markup languages, making it ideal for generating diagrams in text-based formats. This package allows R users to seamlessly integrate the descriptive syntax of 'pikchr' for diagram creation directly within the 'R' environment.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding: UTF-8
RoxygenNote: 7.3.3
VignetteBuilder: knitr
Imports: cli, knitr, brio, htmltools, stringr, rsvg
Suggests: kableExtra, rmarkdown
URL: https://strategicprojects.github.io/pikchr/, https://github.com/StrategicProjects/pikchr
BugReports: https://github.com/StrategicProjects/pikchr/issues
Note: This package makes use of the 'pikchr' source code created by Richard Hipp (<https://pikchr.org>).
Depends: R (≥ 4.0)
LazyData: true
Config/Needs/website: tidyverse/tidytemplate, rmarkdown
NeedsCompilation: yes
Packaged: 2026-04-07 19:18:17 UTC; leite
Author: Andre Leite [aut, cre], Hugo Vaconcelos [aut], Diogo Bezerra [aut], Marcos Wasilew [aut], Carlos Amorin [aut], Richard Hipp [ctb], Brian Kernighan [ctb]
Maintainer: Andre Leite <leite@castlab.org>
Repository: CRAN
Date/Publication: 2026-04-07 19:30:02 UTC

Simple string hash for font dedup

Description

Simple string hash for font dedup

Usage

digest_simple(x)

Arguments

x

Character string.

Value

Character hash.

Pikchr Code Engine for Knitr

Description

A custom knitr engine to render Pikchr diagrams as SVG (HTML output) or PNG (LaTeX, DOCX, and other non-HTML formats). Works with both RMarkdown and Quarto documents.

Usage

eng_pikchr(options)

Arguments

options

A list of chunk options from knitr.

Details

The eng_pikchr function allows you to use Pikchr code inside R Markdown and Quarto documents, rendering it as an image. It supports options like width, height, fontSize, fontFamily, and CSS classes to customize the output.

The engine automatically detects the output format. For HTML-based outputs (html, revealjs, slidy, etc.) the SVG is embedded inline. For non-HTML outputs (LaTeX/PDF, DOCX, EPUB, Typst, etc.) the SVG is converted to PNG via rsvg_png.

Value

Rendered output suitable for the target document format.

Chunk Options

Standard knitr options:

eval

Whether to evaluate the Pikchr code (default TRUE).

echo

Whether to display the code in the output (default TRUE).

fig.cap

Figure caption (supported in both HTML and non-HTML output).

fig.alt

Alternative text for accessibility (HTML only).

fig.align

Figure alignment: "left", "right", "center", or "default".

out.width

Output width for non-HTML formats (e.g., "80%").

dpi

Resolution for PNG conversion in non-HTML output (default 150).

Pikchr-specific options:

width

CSS width of the SVG (default from viewBox, e.g., "80%").

height

CSS height of the SVG (default "auto").

fontSize

Font size for the diagram (default "100%").

fontFamily

Font family for the diagram (default "Jost").

class

CSS class for the SVG element (default "pikchr").

css

Additional inline CSS styles for the SVG.

margin

CSS margin around the SVG (default "10px 0 10px 0").

See Also

pikchr, knit_engines

Validate Knitr Chunk Options for Pikchr Engine

Description

Validates chunk options provided to the Pikchr engine. Numeric values for logical options ('eval', 'echo', 'warning') are converted to 'TRUE' with a warning.

Usage

eng_pikchr_validate_options(options)

Arguments

options

A list of chunk options from knitr.

Value

The validated options list.

Extract SVG intrinsic width from viewBox

Description

Parses the 'viewBox' attribute from an SVG string and returns the width in user units (typically px at 72 dpi).

Usage

extract_svg_width(svg_string)

Arguments

svg_string

Character string containing SVG markup.

Value

Numeric width or 'NULL' if not found.

Google Font List

Description

List of fonts and their styles on the Google Fonts site.

Usage

google_fonts

Format

## 'google_fonts' A data frame with 1,718 rows and 2 columns:

family

Font family names

styles

Font styles

Source

<https://fonts.google.com>

Check if current output requires raster (PNG) images

Description

Returns 'TRUE' for LaTeX/PDF, DOCX, EPUB, Typst, and any non-HTML format. Returns 'FALSE' for all HTML-based outputs (HTML, Revealjs, Slidy, etc.).

Usage

is_raster_output()

Value

Logical scalar.

Convert Pikchr Code to SVG

Description

This function converts a diagram description written in the Pikchr language into an SVG (Scalable Vector Graphics) format. Pikchr is a diagram language inspired by PIC, and this function allows you to easily embed Pikchr diagrams as SVG images in your HTML or Markdown documents.

Usage

pikchr(
  code,
  width = NULL,
  height = NULL,
  fontSize = "100%",
  fontFamily = "Jost",
  class = "pikchr",
  align = "none",
  css = NULL,
  margin = NULL,
  svgOnly = FALSE
)

Arguments

code

A character string containing the diagram code written in the Pikchr language.

width

A character string representing the width of the rendered SVG. It accepts standard HTML values such as percentages ("75%"), pixels ("300px"), or "auto". Defaults to "75%".

height

A character string representing the height of the rendered SVG. It accepts standard HTML values such as pixels ("300px") or "auto". Defaults to "auto".

fontSize

A character string specifying the font size of the text within the SVG. It accepts standard HTML values such as percentages ("80%"), pixels, or keywords ("large"). Defaults to "80%".

fontFamily

A character string specifying the font family for the text in the diagram. Common values include "inherit" (to use the page's default font), "Arial", "Times New Roman", etc. Defaults to "inherit".

class

A character string specifying a CSS class to apply to the SVG. This can be used to style the SVG with external CSS rules. Defaults to "pikchr".

align

A character string specifying the alignment of the SVG within its container. Options are "center" (default), "left", or "right". If set to "none", no alignment is applied.

css

A character string containing extra CSS styles to apply directly to the SVG element. This allows additional customization beyond width, height, and font settings. If NULL, no extra styles are applied.

margin

A character string specifying the margin around the SVG element, formatted like a CSS margin rule (e.g., "10px 0 10px 0"). Defaults to "10px 0 10px 0".

svgOnly

Logical, whether to return only the raw SVG code (TRUE) or open the diagram in the Viewer window (FALSE, default).

Value

A character string containing the SVG diagram code if svgOnly = TRUE. Otherwise, the function opens the diagram in the Viewer window.

Examples

if(interactive()) {
pikchr('
  arrow right 200% "Rmarkdown" "Source"
  box rad 10px "Rmarkdown" "(knitr)" fit
  arrow right 200% "HTML+SVG" "Output"
  arrow <-> down from last box.s
  box same "Pikchr" "(pikchr.c)" fit
  ')
  }

Register a Google Font in the document head

Description

Adds a '<link>' tag to the HTML document head for the given font URL. Each unique URL is registered only once per document, avoiding redundant downloads when multiple pikchr chunks use the same font.

Usage

register_font(font_url)

Arguments

font_url

Character URL of the Google Fonts CSS.

Value

Invisible 'NULL'.

Run Plot Hook and Record Plot Filenames

Description

Records the filename of a plot output in the knitr environment and runs the current plot hook. Used internally for non-HTML outputs (LaTeX, DOCX, etc.).

Usage

run_hook_plot(x, options)

Arguments

x

Character path to the plot file.

options

Knitr chunk options list.

Value

The result of calling the knitr plot hook.