diff --git a/docs/make.jl b/docs/make.jl index e85bbb08..c6d0ac83 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,11 +1,15 @@ using Documenter using DocumenterVitepress -makedocs(; sitename="DocumenterVitepress", authors="LuxDL et al.", +makedocs(; + sitename="DocumenterVitepress", + authors="LuxDL et al.", modules=[DocumenterVitepress], warnonly = true, checkdocs=:all, format=DocumenterVitepress.MarkdownVitepress(), draft=false, source="src", build=joinpath(@__DIR__, "docs_site") -) \ No newline at end of file +) + +# To edit the sidebar, you must edit `docs/src/.vitepress/config.mts`. \ No newline at end of file diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts index 33b790ef..1841cbc0 100644 --- a/docs/src/.vitepress/config.mts +++ b/docs/src/.vitepress/config.mts @@ -41,7 +41,6 @@ export default defineConfig({ items: [ { text: 'Code Example', link: '/code_example' }, { text: 'Markdown Examples', link: '/markdown-examples' }, - { text: 'Tables', link: '/tables' }, { text: 'Runtime API Examples', link: '/api-examples' } ] } diff --git a/docs/src/markdown-examples.md b/docs/src/markdown-examples.md index 1e04fc58..7d4414a5 100644 --- a/docs/src/markdown-examples.md +++ b/docs/src/markdown-examples.md @@ -32,6 +32,52 @@ export default { } ``` +### Code groups + +::: code-group + +```js [config.js] +/** + * @type {import('vitepress').UserConfig} + */ +const config = { + // ... +} + +export default config +``` + +```ts [config.ts] +import type { UserConfig } from 'vitepress' + +const config: UserConfig = { + // ... +} + +export default config +``` + +::: + +### Code focus + +```js +export default { + data () { + return { + msg: 'Focused!' // [!code focus] + } + } +} +``` +### Lists + +1. a +1. b + 1. c + 1. d +1. e + ## Custom Containers **Input** @@ -160,6 +206,31 @@ d content 2 :::: + +## GitHub-flavored Alerts +See: https://vitepress.dev/guide/markdown#github-flavored-alerts + +> [!WARNING] +> Critical content. + +## Tables +See: https://vitepress.dev/guide/markdown#github-style-tables + +| Tables | Are | Cool | +| ------------- | :-----------: | ----: | +| col 3 is | right-aligned | \$1600 | +| col 2 is | centered | \$12 | +| zebra stripes | are neat | \$1 | + +## Equations + +When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are + +$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$ + +Don't type anything after the last double dollar sign, and make sure there are no spaces after the opening double dollar sign in the display math! + + ## More Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown). diff --git a/docs/src/tables.md b/docs/src/tables.md deleted file mode 100644 index 7dcae356..00000000 --- a/docs/src/tables.md +++ /dev/null @@ -1,65 +0,0 @@ -This is currently broken: - -:cold_face: :100: - -## GitHub-flavored Alerts don't work -See: https://vitepress.dev/guide/markdown#github-flavored-alerts - -> [!WARNING] -> Critical content. - -## Tables don't work -See: https://vitepress.dev/guide/markdown#github-style-tables - -| Tables | Are | Cool | -| ------------- | :-----------: | ----: | -| col 3 is | right-aligned | \$1600 | -| col 2 is | centered | \$12 | -| zebra stripes | are neat | \$1 | - -## Equations work - -When \$a \ne 0\$, there are two solutions to \$(ax^2 + bx + c = 0)\$ and they are - -\$\$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} \$\$ - -Don't type anything after the last doulbe dollar sign. - -## Code groups work - -::: code-group - -```js [config.js] -/** - * @type {import('vitepress').UserConfig} - */ -const config = { - // ... -} - -export default config -``` - -```ts [config.ts] -import type { UserConfig } from 'vitepress' - -const config: UserConfig = { - // ... -} - -export default config -``` - -::: - -## code focus - -```js -export default { - data () { - return { - msg: 'Focused!' // [!code focus] - } - } -} -``` \ No newline at end of file diff --git a/src/writer.jl b/src/writer.jl index 27b5f1e7..f9220ab6 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -336,6 +336,7 @@ function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Nod print(io, text.text) end # Bold text (strong) +# These are wrapper elements - so the wrapper doesn't actually contain any text, the current node's children do. function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, strong::MarkdownAST.Strong, page, doc) # @infiltrate print(io, "**") @@ -381,29 +382,86 @@ function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Nod end # Admonitions function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, admonition::MarkdownAST.Admonition, page, doc) - # @infiltrate + # Main.@infiltrate println(io, "\n::: $(admonition.category) $(admonition.title)") render(io, mime, node, node.children, page, doc) println(io, "\n:::") end +# Block quotes +function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, q::MarkdownAST.BlockQuote, page, doc) + # Main.@infiltrate + iob = IOBuffer() + render(iob, mime, node, node.children, page, doc) + output = String(take!(iob)) + eachline = split(output, '\n') + println.((io,), "> " .* eachline) +end +# Inline math +function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, math::MarkdownAST.InlineMath, page, doc) + # Main.@infiltrate + print(io, "\$", math.math, "\$") +end +# Display math +function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, math::MarkdownAST.DisplayMath, page, doc) + # Main.@infiltrate + println(io) + println(io, "\$\$", math.math, "\$\$") +end # Lists # TODO: list ordering is broken! function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, list::MarkdownAST.List, page, doc) # @infiltrate - if list.type === :ordered - println(io) - for (i, item) in enumerate(node.children) - print(io, "$(i). ") - render(io, mime, item, item.children, page, doc) - print(io, "\n") - end - else - for item in node.children - print(io, "- ") - render(io, mime, item, item.children, page, doc) - print(io, "\n") + bullet = list.type === :ordered ? "1. " : "- " + iob = IOBuffer() + for item in node.children + render(iob, mime, item, item.children, page, doc) + eachline = split(String(take!(iob)), '\n') + print(io, bullet) + println.((io,), " " .* eachline) + end +end +# Tables +function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, table::MarkdownAST.TableCell, page, doc) + println("Encountered table cell!") +end + +function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, table::MarkdownAST.Table, page, doc) + th_row, tbody_rows = Iterators.peel(MarkdownAST.tablerows(node)) + # function mdconvert(t::Markdown.Table, parent; kwargs...) + alignment_style = map(table.spec) do align + if align == :right + "text-align: right" + elseif align == :center + "text-align: center" + else + "text-align: left" end end + # We now emit a HTML table, which is of course styled by CSS - so that images etc. can be included more easily, + # without worrying about Markdown spacing issues. + println(io, "") # begin table + println(io, "") + println(io, "") # begin header row + # Main.@infiltrate + for (cell, align) in zip(th_row.children, alignment_style) + print(io, "") + end + println(io, "") # end header row + println(io, "") + println(io, "") + for row in tbody_rows + println(io, "") # begin row + for (cell, align) in zip(row.children, alignment_style) + print(io, "") end + println(io, "") # end row + end + println(io, "") + println(io, "
") + render(io, mime, cell, cell.children, page, doc) + println(io, "
") + render(io, mime, cell, cell.children, page, doc) + println(io, "
") # end table + end # Images function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, image::MarkdownAST.Image, page, doc)