1 | ---
|
2 | in_progress: yes
|
3 | ---
|
4 |
|
5 | Examples of HTML Plugins
|
6 | ========================
|
7 |
|
8 | This file is essentially a unit test for [doctools/oils_doc.py]($oils-src), which
|
9 | contains all the HTML plugins.
|
10 |
|
11 | Related: [How We Build Oils Documentation](doc-toolchain.html).
|
12 |
|
13 | <div id="toc">
|
14 | </div>
|
15 |
|
16 | ## Link Shortcuts with `$`
|
17 |
|
18 | - `$xref`: [bash]($xref)
|
19 | - `$blog-tag`: [oil-release]($blog-tag)
|
20 | - `$oils-src`: [INSTALL.txt]($oils-src), [INSTALL.txt]($oils-src:INSTALL.txt)
|
21 | - `$blog-code-src`: [interactive-shell/README.md]($blog-code-src)
|
22 | - `$issue`: [issue 11]($issue:11)
|
23 | - `$oils-commit`: [this commit]($oils-commit:a1dad10d53b1fb94a164888d9ec277249ae98b58)
|
24 |
|
25 | ## Syntax Highlighting Specified In Front matter
|
26 |
|
27 | If every `pre` block in a document needs the same highlighter, you can specify
|
28 | it in the front matter like this:
|
29 |
|
30 | ---
|
31 | default_highlighter: oils-sh
|
32 | ---
|
33 |
|
34 | My Title
|
35 | ========
|
36 |
|
37 | ## Syntax Highlighting With Fenced Code Blocks
|
38 |
|
39 | ### sh-prompt
|
40 |
|
41 | Highlights the `$` line. For example, this input
|
42 |
|
43 | ```sh-prompt
|
44 | $ echo hi # comment
|
45 | hi
|
46 | ```
|
47 |
|
48 | produces
|
49 |
|
50 | ```sh-prompt
|
51 | $ echo hi # comment
|
52 | hi
|
53 | ```
|
54 |
|
55 | ### oils-sh
|
56 |
|
57 | A generic formatter that works for both shell and YSH code. It's used in
|
58 | [idioms.html](idioms.html), [known differences](known-differences.html), and is
|
59 | now the default for the Oils blog.
|
60 |
|
61 | (Detail: it's the same as `sh-prompt` for now. We might want to do something
|
62 | smarter.)
|
63 |
|
64 | ### none (Explicit Override)
|
65 |
|
66 | To override the default highlighter with none:
|
67 |
|
68 | ```none
|
69 | $ echo 'no syntax highlighting'
|
70 | ```
|
71 |
|
72 | Result:
|
73 |
|
74 | ```none
|
75 | $ echo 'no syntax highlighting'
|
76 | ```
|
77 |
|
78 | ### Pygments Lexers
|
79 |
|
80 | Use any pygments lexer:
|
81 |
|
82 | ```python
|
83 | x = 42
|
84 | print(x, file=sys.stderr)
|
85 | ```
|
86 |
|
87 | produces
|
88 |
|
89 | ```python
|
90 | x = 42
|
91 | print(x, file=sys.stderr)
|
92 | ```
|
93 |
|
94 | ### Plugins We Should Have
|
95 |
|
96 | - ysh and osh. *A Tour of YSH* could use it to show which code blocks can be
|
97 | extracted and run.
|
98 | - Side-by-side sh and YSH
|
99 | - Side-by-side PCRE and Eggex
|
100 | - sh-session - How to replace the data?
|
101 |
|
102 | A shell session could look like this:
|
103 |
|
104 | ```session-bash
|
105 | $ echo one
|
106 | one
|
107 |
|
108 | $ for x in foo bar; do
|
109 | > echo $x
|
110 | > done
|
111 | foo
|
112 | bar
|
113 | ```
|
114 |
|
115 | or
|
116 |
|
117 | ```session-ysh
|
118 | $ echo one
|
119 | one
|
120 |
|
121 | $ for x in foo bar {
|
122 | > echo $x
|
123 | > }
|
124 | foo
|
125 | bar
|
126 | ```
|
127 |
|
128 | <!--
|
129 | Workflow:
|
130 | - You should write this directly in Markdown. Even the output. So you know
|
131 | what you expect.
|
132 | - Syntax highlighter:
|
133 | - $ and > lines prefixes in bold, with the code in blue
|
134 | - the rest of the output in black
|
135 | - Verifier
|
136 | - Will extract:
|
137 | 1. sequences of lines that begin with $ and continue with >
|
138 | 2. expected output (not beginning with $ or >)
|
139 | - It will run those in a CLEAN working directory, one after the other
|
140 | - maybe it inserts 'echo __MAGIC_DELIMITER__ between them?
|
141 | - Or you could use the headless shell! To preserve state!
|
142 | - And then it will diff the actual output vs. the expected output
|
143 |
|
144 | Another idea: PS2 should lead with the same number of spaces as PS1:
|
145 |
|
146 | ysh$ for x in foo bar {
|
147 | . echo $x
|
148 | . }
|
149 | foo
|
150 | bar
|
151 |
|
152 | This looks cleaner.
|
153 | -->
|
154 |
|
155 | Embeddings:
|
156 |
|
157 | - Embed Image Preview of Web Page?
|
158 | - Embed Github Commit?
|
159 | - hashdiv has this for stories
|
160 | - Graphviz
|
161 | - LaTeX (although I don't really use it)
|
162 |
|