build: add recipes for processing markdown figures

tools/make/lib/ls/Makefile

@@ -239,6 +239,13 @@ SVG_EQUATIONS_PATTERN ?= equation*.$(SVG_FILENAME_EXT)
 SVG_EQUATIONS_FILTER ?= .*/.*
 
 
+# Define a filename pattern for SVG figure files:
+SVG_FIGURES_PATTERN ?= fig*.$(SVG_FILENAME_EXT)
+
+# Define a filepath pattern for SVG figure files:
+SVG_FIGURES_FILTER ?= .*/.*
+
+
 # Define a filename pattern for TypeScript files:
 TYPESCRIPT_PATTERN ?= *.$(TYPESCRIPT_FILENAME_EXT)
 
@@ -441,6 +448,7 @@ include $(TOOLS_MAKE_LIB_DIR)/ls/python/Makefile
 include $(TOOLS_MAKE_LIB_DIR)/ls/r/Makefile
 include $(TOOLS_MAKE_LIB_DIR)/ls/shell/Makefile
 include $(TOOLS_MAKE_LIB_DIR)/ls/svg_equations.mk
+include $(TOOLS_MAKE_LIB_DIR)/ls/svg_figures.mk
 include $(TOOLS_MAKE_LIB_DIR)/ls/tests_directories.mk
 include $(TOOLS_MAKE_LIB_DIR)/ls/tests_fixtures.mk
 include $(TOOLS_MAKE_LIB_DIR)/ls/tools_tests_directories.mk

tools/make/lib/ls/svg_figures.mk

@@ -0,0 +1,49 @@
+#/
+# @license Apache-2.0
+#
+# Copyright (c) 2026 The Stdlib Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#/
+
+# VARIABLES #
+
+# Define the command flags:
+FIND_SVG_FIGURES_FLAGS ?= \
+	-type f \
+	-name "$(SVG_FIGURES_PATTERN)" \
+	-path "$(ROOT_DIR)/**/$(DOCUMENTATION_FOLDER)/**" \
+	-regex "$(SVG_FIGURES_FILTER)" \
+	$(FIND_SVG_EQUATIONS_EXCLUDE_FLAGS)
+
+ifneq ($(OS), Darwin)
+	FIND_SVG_FIGURES_FLAGS := -regextype posix-extended $(FIND_SVG_FIGURES_FLAGS)
+endif
+
+# Define a command for listing SVG figure files:
+FIND_SVG_FIGURES_CMD ?= find $(find_kernel_prefix) $(ROOT_DIR) $(FIND_SVG_FIGURES_FLAGS)
+
+# Define the list of files:
+SVG_FIGURE_FILES ?= $(shell $(FIND_SVG_FIGURES_CMD))
+
+
+# TARGETS #
+
+# List all SVG figure files.
+#
+# This target prints a list of all SVG figure files.
+
+list-svg-figure-files:
+	$(QUIET) find $(find_kernel_prefix) $(ROOT_DIR) $(FIND_SVG_FIGURES_FLAGS) $(find_print_list)
+
+.PHONY: list-svg-figure-files

tools/make/lib/markdown/Makefile

@@ -21,6 +21,7 @@
 # Note: keep in alphabetical order...
 include $(TOOLS_MAKE_LIB_DIR)/markdown/assets.mk
 include $(TOOLS_MAKE_LIB_DIR)/markdown/equations.mk
+include $(TOOLS_MAKE_LIB_DIR)/markdown/figures.mk
 include $(TOOLS_MAKE_LIB_DIR)/markdown/includes.mk
 include $(TOOLS_MAKE_LIB_DIR)/markdown/namespace_toc.mk
 include $(TOOLS_MAKE_LIB_DIR)/markdown/pkg_urls.mk

tools/make/lib/markdown/figures.mk

@@ -0,0 +1,220 @@
+#/
+# @license Apache-2.0
+#
+# Copyright (c) 2026 The Stdlib Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#/
+
+# VARIABLES #
+
+# Define the command to commit staged files after processing Markdown figures:
+GIT_COMMIT_FIGURES ?= $(GIT_COMMIT) -m 'Process Markdown figures'
+
+# Define the command to commit staged files after inserting resource URLs:
+GIT_COMMIT_FIGURES_SRC_URLS ?= $(GIT_COMMIT) -m 'Insert src urls into figure elements'
+
+# Define the path relative to a processed Markdown file for storing figure resources:
+FIGURE_RESOURCES_PATH ?= ./docs/img/
+
+# Define the path to the remark configuration file:
+REMARK_FIGURES_CONF ?= $(CONFIG_DIR)/remark/.remarkrc.js
+
+# Define the path to the remark ignore file:
+REMARK_FIGURES_IGNORE ?= $(ROOT_DIR)/.remarkignore
+
+# Define the path to a plugin which processes Markdown figure comments:
+REMARK_IMG_FIGURES_PLUGIN ?= $(TOOLS_PKGS_DIR)/remark/plugins/remark-img-figures
+REMARK_IMG_FIGURES_PLUGIN_SETTINGS ?=
+REMARK_IMG_FIGURES_PLUGIN_FLAGS ?= --use $(REMARK_IMG_FIGURES_PLUGIN)=$(REMARK_IMG_FIGURES_PLUGIN_SETTINGS)
+
+# Define the path to a plugin which inserts resource URLs into Markdown image figure elements:
+REMARK_IMG_FIGURES_SRC_URLS_PLUGIN ?= $(TOOLS_PKGS_DIR)/remark/plugins/remark-img-figures-src-urls
+REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_SETTINGS ?= '"'dir'"':'"'$(FIGURE_RESOURCES_PATH)'"'
+REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_FLAGS ?= --use $(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN)=$(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_SETTINGS)
+
+# Define command-line options when invoking the remark executable:
+REMARK_FIGURES_FLAGS ?= \
+	--ext $(MARKDOWN_FILENAME_EXT) \
+	--rc-path $(REMARK_FIGURES_CONF) \
+	--ignore-path $(REMARK_FIGURES_IGNORE)
+
+# Define the remark output option:
+REMARK_FIGURES_OUTPUT_FLAG ?= --output
+
+
+# RULES #
+
+#/
+# Processes Markdown files containing Markdown figure elements.
+#
+# ## Notes
+#
+# -   Processing happens as follows:
+#
+#     1.  Files containing figure comments are transformed to include figure elements.
+#     2.  Processed files are committed to source control.
+#     3.  Resource URLs are inserted into image figure elements.
+#     4.  Processed files are committed to source control.
+#
+# -   This rule is useful when wanting to glob for Markdown files (e.g., process all Markdown files for a particular package).
+#
+# @param {string} [MARKDOWN_FILTER] - file path pattern (e.g., `.*/plot/vega/.*`)
+# @param {string} [MARKDOWN_PATTERN] - filename pattern (e.g., `*.md`)
+#
+# @example
+# make markdown-figures
+#
+# @example
+# make markdown-figures MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/plot/vega/.*'
+#/
+markdown-figures: $(NODE_MODULES) assert-clean-working-directory
+	$(QUIET) $(REMARK) $(MARKDOWN_FILES) \
+		$(REMARK_FIGURES_FLAGS) \
+		$(REMARK_IMG_FIGURES_PLUGIN_FLAGS) \
+		$(REMARK_FIGURES_OUTPUT_FLAG) && \
+	$(GIT_ADD) -A && $(GIT_COMMIT_FIGURES) && \
+	$(REMARK) $(MARKDOWN_FILES) \
+		$(REMARK_FIGURES_FLAGS) \
+		$(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_FLAGS) \
+		$(REMARK_FIGURES_OUTPUT_FLAG) && \
+	$(GIT_ADD) -A && $(GIT_COMMIT_FIGURES_SRC_URLS)
+
+.PHONY: markdown-figures
+
+#/
+# Transforms Markdown files containing figure comment markup to include image figure elements.
+#
+# ## Notes
+#
+# -   This rule is useful when wanting to glob for Markdown files (e.g., process all Markdown files for a particular package).
+#
+# @param {string} [MARKDOWN_FILTER] - file path pattern (e.g., `.*/plot/vega/.*`)
+# @param {string} [MARKDOWN_PATTERN] - filename pattern (e.g., `*.md`)
+#
+# @example
+# make markdown-img-figures
+#
+# @example
+# make markdown-img-figures MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/plot/vega/.*'
+#/
+markdown-img-figures: $(NODE_MODULES)
+	$(QUIET) $(FIND_MARKDOWN_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
+		echo ""; \
+		echo "Processing file: $$file"; \
+		"$(REMARK)" \
+			$$file \
+			$(REMARK_FIGURES_FLAGS) \
+			$(REMARK_IMG_FIGURES_PLUGIN_FLAGS) \
+			$(REMARK_FIGURES_OUTPUT_FLAG) || exit 1; \
+	done
+
+.PHONY: markdown-img-figures
+
+#/
+# Transforms a specified list of Markdown files containing figure comment markup to include image figure elements.
+#
+# ## Notes
+#
+# -   This rule is useful when wanting to process a list of Markdown files generated by some other command (e.g., a list of changed Markdown files obtained via `git diff`).
+#
+# @param {string} FILES - list of files
+#
+# @example
+# make markdown-img-figures-files FILES='/foo/foo.md /foo/bar.md'
+#/
+markdown-img-figures-files: $(NODE_MODULES)
+	$(QUIET) for file in $(FILES); do \
+		echo ""; \
+		echo "Processing file: $$file"; \
+		"$(REMARK)" \
+			$$file \
+			$(REMARK_FIGURES_FLAGS) \
+			$(REMARK_IMG_FIGURES_PLUGIN_FLAGS) \
+			$(REMARK_FIGURES_OUTPUT_FLAG) || exit 1; \
+	done
+
+.PHONY: markdown-img-figures-files
+
+#/
+# Inserts resource URLs into Markdown image figure elements.
+#
+# ## Notes
+#
+# -   This rule is useful when wanting to glob for Markdown files (e.g., process all Markdown files for a particular package).
+# -   This recipe assumes that image SVG figure files already exist and have been committed to source control.
+#
+# @param {string} [MARKDOWN_FILTER] - file path pattern (e.g., `.*/plot/vega/.*`)
+# @param {string} [MARKDOWN_PATTERN] - filename pattern (e.g., `*.md`)
+#
+# @example
+# make markdown-img-figures-src-urls
+#
+# @example
+# make markdown-img-figures-src-urls MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/plot/vega/.*'
+#/
+markdown-img-figures-src-urls: $(NODE_MODULES)
+	$(QUIET) $(FIND_MARKDOWN_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
+		echo ""; \
+		echo "Processing file: $$file"; \
+		"$(REMARK)" \
+			$$file \
+			$(REMARK_FIGURES_FLAGS) \
+			$(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_FLAGS) \
+			$(REMARK_FIGURES_OUTPUT_FLAG) || exit 1; \
+	done
+
+.PHONY: markdown-img-figures-src-urls
+
+#/
+# Inserts resource URLs into Markdown image figure elements for a specified list of files.
+#
+# ## Notes
+#
+# -   This rule is useful when wanting to process a list of Markdown files generated by some other command (e.g., a list of changed Markdown files obtained via `git diff`).
+# -   This recipe assumes that image SVG figure files already exist and have been committed to source control.
+#
+# @param {string} FILES - list of files
+#
+# @example
+# make markdown-img-figures-src-urls-files FILES='/foo/foo.md /foo/bar.md'
+#/
+markdown-img-figures-src-urls-files: $(NODE_MODULES)
+	$(QUIET) for file in $(FILES); do \
+		echo ""; \
+		echo "Processing file: $$file"; \
+		"$(REMARK)" \
+			$$file \
+			$(REMARK_FIGURES_FLAGS) \
+			$(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_FLAGS) \
+			$(REMARK_FIGURES_OUTPUT_FLAG) || exit 1; \
+	done
+
+.PHONY: markdown-img-figures-src-urls-files
+
+#/
+# Removes SVG figure files.
+#
+# @param {string} [SVG_FIGURES_FILTER] - file path pattern (e.g., `.*/plot/vega/.*`)
+# @param {string} [SVG_FIGURES_PATTERN] - filename pattern (e.g., `fig*.svg`)
+#
+# @example
+# make clean-markdown-svg-figures
+#
+# @example
+# make clean-markdown-svg-figures SVG_FIGURES_PATTERN='fig*.svg' SVG_FIGURES_FILTER='.*/plot/vega/.*'
+#/
+clean-markdown-svg-figures:
+	$(QUIET) $(DELETE) -f $(SVG_FIGURE_FILES)
+
+.PHONY: clean-markdown-svg-figures