├── README.md
└── ast.md


/README.md:
--------------------------------------------------------------------------------
 1 | Markdown AST spec
 2 | =================
 3 | 
 4 | Working draft to design lossless AST for markdown. Unstable.
 5 | 
 6 | Use [issues tracker](https://github.com/markdown-it/markdown-ast-spec/issues)
 7 | to discuss.
 8 | 
 9 | **Goals & checkpoints**:
10 | 
11 | 1. Allow support use cases, not available with current implementations. Examples:
12 |     - Optimize editor highlight update after text change.
13 |     - When user selects range at html page, provide range in source markdown doc.
14 |     - Better sync scroll for previews.
15 | 2. Provide source mapping info.
16 | 3. Allow AST -> markdown write without formatting loss.
17 | 4. Performance:
18 |     - Additional care should be applied to fast AST build/traverse in Javascript.
19 | 5. Analyse required operation and recommend minimal set of API functions.
20 | 
21 | ---
22 | 
23 | Useful to read:
24 | 
25 | - [csstree](https://github.com/csstree/csstree) - interesting approach to fast
26 |   tokenizer and other optimizations.
27 | - [ESTree](https://github.com/estree/estree) - lossless JS AST design.
28 | - [AST Explorer](http://astexplorer.net/) - explore different AST implementations.
29 | 


--------------------------------------------------------------------------------
/ast.md:
--------------------------------------------------------------------------------
  1 | Markdown-it AST spec
  2 | ====================
  3 | 
  4 | Methods
  5 | -------
  6 | 
  7 | - `clone(AST)`
  8 | - `walk(AST, handler)`
  9 | - `toJSON()`
 10 | 
 11 | TODO (or check possibility):
 12 | 
 13 | - walk inlines
 14 | - walk blocks (+ deepness?)
 15 | - partial text node replace
 16 |   - by text
 17 |   - by nodes (linkify, for example)
 18 | - parse
 19 | - from JSON
 20 | - to HTML
 21 | 
 22 | 
 23 | Nodes
 24 | -----
 25 | 
 26 | ### Abstract node
 27 | 
 28 | Fields:
 29 | 
 30 | - `type`
 31 | - `children` - childrens list if available
 32 | 
 33 | TODO:
 34 | 
 35 | - sourcemap data
 36 | - optimize traverse
 37 | - check required transforms and optimize those
 38 | 
 39 | ### Blockquote
 40 | 
 41 | ```
 42 | > foo **bar
 43 | >baz**
 44 | cad
 45 | ```
 46 | 
 47 | =>
 48 | 
 49 | ```js
 50 | {
 51 |   type: 'document',
 52 |   children: [
 53 |     {
 54 |       type: 'blockquote',
 55 |       children: [
 56 |         type: 'p',
 57 |         children: [
 58 |           type: 'inline'
 59 |           children: [
 60 |             {
 61 |               type: 'indent',
 62 |               value: '> '
 63 |             }
 64 |             {
 65 |               type: 'text',
 66 |               value: 'foo '
 67 |             }
 68 |             {
 69 |               type: 'bold',
 70 |               marker: '**'
 71 |               children: [
 72 |                 {
 73 |                   type: 'text',
 74 |                   value: 'bar'
 75 |                 }
 76 |                 {
 77 |                   type: 'softbreak',
 78 |                   value: '\n'
 79 |                 },
 80 |                 {
 81 |                   type: 'indent',
 82 |                   value: '>'
 83 |                 }
 84 |                 {
 85 |                   type: 'text',
 86 |                   value: 'bad'
 87 |                 }
 88 |                 {
 89 |                   type: 'softbreak',
 90 |                   value: '\n'
 91 |                 },
 92 |                 {
 93 |                   type: 'text',
 94 |                   value: 'cad'
 95 |                 }
 96 |               ]
 97 |             }
 98 |           ]
 99 |         ]
100 |       ]      
101 |     }
102 |   ]
103 | }
104 | ```
105 | 
106 | 
107 | # List
108 | 
109 | ```
110 | -  foo
111 |  - bar
112 | baz
113 | ```
114 | 
115 | =>
116 | 
117 | ```js
118 | {
119 |   type: 'document',
120 |   kind: 'block'
121 |   children: [
122 |     {
123 |       type: 'ul',
124 |       children: [
125 |         {
126 |           type: 'li',
127 |           marker: '-'
128 |           children: [
129 |             {
130 |               type: 'inline',
131 |               children: [
132 |                 {
133 |                   type: 'indent',
134 |                   value: '- '
135 |                 }
136 |                 {
137 |                   type: 'text',
138 |                   value: 'foo'
139 |                 }                
140 |                 {
141 |                   type: 'softbreak',
142 |                   value: '\n'
143 |                 },
144 |               ]
145 |             }
146 |           ],
147 |         },
148 |         {
149 |           type: 'li',
150 |           marker: '-'
151 |           children: [
152 |             {
153 |               type: 'inline',
154 |               children: [
155 |                 {
156 |                   type: 'indent',
157 |                   value: ' - '
158 |                 }
159 |                 {
160 |                   type: 'text',
161 |                   value: 'bar'
162 |                 }                
163 |                 {
164 |                   type: 'br',
165 |                   soft: true,
166 |                   value: '\n'
167 |                 },
168 |                 {
169 |                   type: 'text',
170 |                   value: 'baz'
171 |                 }                
172 |               ]
173 |             }
174 |           ],
175 |         }
176 |       ]
177 |     }
178 |   ]
179 | }
180 | ```
181 | 


--------------------------------------------------------------------------------