Skip to content

Commit 83e18c8

Browse files
kgrytekgryte
committed
Update rules for managing Markdown files
1 parent 7eb054e commit 83e18c8

File tree

6 files changed

+379
-89
lines changed

6 files changed

+379
-89
lines changed

‎tools/make/lib/markdown/Makefile‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@
1818

1919
# DEPENDENCIES #
2020

21-
include $(TOOLS_MAKE_LIB_DIR)/markdown/asset_links.mk
21+
# Note: keep in alphabetical order...
22+
include $(TOOLS_MAKE_LIB_DIR)/markdown/assets.mk
2223
include $(TOOLS_MAKE_LIB_DIR)/markdown/equations.mk
2324
include $(TOOLS_MAKE_LIB_DIR)/markdown/namespace_toc.mk
25+
include $(TOOLS_MAKE_LIB_DIR)/markdown/pkg_urls.mk

‎tools/make/lib/markdown/README.md‎

Lines changed: 207 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,222 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2021 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
121
# Markdown
222

3-
> Markdown recipes.
23+
> Markdown commands.
424
525
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
626

727
<section class="intro">
828

9-
This directory contains [`make`][make] recipes for managing Markdown files.
29+
This directory contains [`make`][make] rules for managing Markdown files.
1030

1131
</section>
1232

1333
<!-- /.intro -->
1434

35+
<!-- Usage documentation. -->
36+
37+
<section class="usage">
38+
39+
## Usage
40+
41+
```text
42+
Usage: make <command> [<ENV_VAR>=<value> <ENV_VAR>=<value> ...]
43+
```
44+
45+
### Commands
46+
47+
#### markdown-asset-url
48+
49+
Generates an asset URL (derived from the current Git hash) for inclusion in a project Markdown file.
50+
51+
<!-- run-disable -->
52+
53+
```bash
54+
$ make markdown-asset-url MARKDOWN_ASSET_PATH='./README.md'
55+
```
56+
57+
The command supports the following environment variables:
58+
59+
- **MARKDOWN_ASSET_PATH**: a file path relative to the project root directory; e.g., `./README.md`.
60+
61+
#### markdown-namespace-tocs
62+
63+
Updates the table of contents of namespace Markdown files.
64+
65+
<!-- run-disable -->
66+
67+
```bash
68+
$ make markdown-namespace-tocs
69+
```
70+
71+
The command supports the following environment variables:
72+
73+
- **MARKDOWN_PATTERN**: filename pattern; e.g., `*.md`.
74+
- **MARKDOWN_FILTER**: file path pattern; e.g., `.*/math/base/special/.*`
75+
76+
<!-- run-disable -->
77+
78+
```bash
79+
$ make markdown-namespace-tocs MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/math/base/special/.*'
80+
```
81+
82+
#### markdown-pkg-urls
83+
84+
Updates Markdown files by resolving package identifiers to GitHub repository URLs.
85+
86+
<!-- run-disable -->
87+
88+
```bash
89+
$ make markdown-pkg-urls
90+
```
91+
92+
The command supports the following environment variables:
93+
94+
- **MARKDOWN_PATTERN**: filename pattern; e.g., `*.md`.
95+
- **MARKDOWN_FILTER**: file path pattern; e.g., `.*/math/base/special/.*`
96+
97+
<!-- run-disable -->
98+
99+
```bash
100+
$ make markdown-pkg-urls MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/math/base/special/.*'
101+
```
102+
103+
* * *
104+
105+
### Equations
106+
107+
#### markdown-equations
108+
109+
Processes Markdown files containing Markdown equation elements.
110+
111+
<!-- run-disable -->
112+
113+
```bash
114+
$ make markdown-equations
115+
```
116+
117+
The command supports the following environment variables:
118+
119+
- **MARKDOWN_PATTERN**: filename pattern; e.g., `*.md`.
120+
- **MARKDOWN_FILTER**: file path pattern; e.g., `.*/math/base/special/.*`
121+
122+
<!-- run-disable -->
123+
124+
```bash
125+
$ make markdown-equations MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/math/base/special/.*'
126+
```
127+
128+
Processed files are committed to source control. Accordingly, this command must be run on a clean working directory.
129+
130+
#### markdown-img-equations
131+
132+
Transforms Markdown files containing equation comment markup to include image equation elements.
133+
134+
<!-- run-disable -->
135+
136+
```bash
137+
$ make markdown-img-equations
138+
```
139+
140+
The command supports the following environment variables:
141+
142+
- **MARKDOWN_PATTERN**: filename pattern; e.g., `*.md`.
143+
- **MARKDOWN_FILTER**: file path pattern; e.g., `.*/math/base/special/.*`
144+
145+
<!-- run-disable -->
146+
147+
```bash
148+
$ make markdown-img-equations MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/math/base/special/.*'
149+
```
150+
151+
#### markdown-img-equations-src-urls
152+
153+
Inserts resource URLs into Markdown image equation elements.
154+
155+
<!-- run-disable -->
156+
157+
```bash
158+
$ make markdown-img-equations-src-urls
159+
```
160+
161+
The command supports the following environment variables:
162+
163+
- **MARKDOWN_PATTERN**: filename pattern; e.g., `*.md`.
164+
- **MARKDOWN_FILTER**: file path pattern; e.g., `.*/math/base/special/.*`
165+
166+
<!-- run-disable -->
167+
168+
```bash
169+
$ make markdown-img-equations-src-urls MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/math/base/special/.*'
170+
```
171+
172+
This command assumes that image SVG equation files already exist and have been committed to source control. See `markdown-svg-equations`.
173+
174+
#### markdown-svg-equations
175+
176+
Generates SVG equation files from Markdown equation comments.
177+
178+
<!-- run-disable -->
179+
180+
```bash
181+
$ make markdown-svg-equations
182+
```
183+
184+
The command supports the following environment variables:
185+
186+
- **MARKDOWN_PATTERN**: filename pattern; e.g., `*.md`.
187+
- **MARKDOWN_FILTER**: file path pattern; e.g., `.*/math/base/special/.*`
188+
189+
<!-- run-disable -->
190+
191+
```bash
192+
$ make markdown-svg-equations MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/math/base/special/.*'
193+
```
194+
195+
#### clean-markdown-svg-equations
196+
197+
Removes SVG equation files.
198+
199+
<!-- run-disable -->
200+
201+
```bash
202+
$ make clean-markdown-svg-equations
203+
```
204+
205+
The command supports the following environment variables:
206+
207+
- **SVG_EQUATIONS_PATTERN**: filename pattern; e.g., `equation*.svg`.
208+
- **SVG_EQUATIONS_FILTER**: file path pattern; e.g., `.*/math/base/special/.*`
209+
210+
<!-- run-disable -->
211+
212+
```bash
213+
$ make clean-markdown-svg-equations SVG_EQUATIONS_PATTERN='equation*.svg' SVG_EQUATIONS_FILTER='.*/math/base/special/.*'
214+
```
215+
216+
</section>
217+
218+
<!-- /.usage -->
219+
15220
<!-- Section to include notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
16221

17222
<section class="notes">

tools/make/lib/markdown/asset_links.mk renamed to tools/make/lib/markdown/assets.mk

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,13 +32,21 @@ JSDELIVR_URL_FLAGS ?= \
3232
--slug stdlib-js/stdlib/$(JSDELIVR_COMMIT_HASH)
3333

3434

35-
# TARGETS #
35+
# RULES #
3636

37-
# Generate an asset link.
37+
#/
38+
# Generates an asset URL for inclusion in a project Markdown file.
3839
#
39-
# This target generates an asset link based on the current Git hash for inclusion in a project Markdown file.
40-
41-
markdown-asset-link: $(NODE_MODULES)
40+
# ## Notes
41+
#
42+
# - The asset URL is derived the current Git hash.
43+
#
44+
# @param {string} MARKDOWN_ASSET_PATH - asset file path relative to the project root directory (e.g., `MARKDOWN_ASSET_PATH=./README.md`)
45+
#
46+
# @example
47+
# make markdown-asset-url MARKDOWN_ASSET_PATH='./README.md'
48+
#/
49+
markdown-asset-url: $(NODE_MODULES)
4250
$(QUIET) NODE_PATH="$(NODE_PATH)" $(JSDELIVR_URL) $(JSDELIVR_URL_FLAGS) $(MARKDOWN_ASSET_PATH)
4351

44-
.PHONY: markdown-asset-link
52+
.PHONY: markdown-asset-url

0 commit comments

Comments
 (0)