A bit more in docs (#14)

* Update getting_started.md

* add a bit more stuff

* doc improvements - try to have it build!

docs/make.jl

@@ -21,7 +21,7 @@ makedocs(; sitename="DocumenterVitepress",
 deploy_config = Documenter.auto_detect_deploy_system()
 deploy_decision = Documenter.deploy_folder(
     deploy_config;
-    repo="github.com/LuxDL/DocumenterVitepress.jl",
+    repo="github.com/LuxDL/DocumenterVitepress.jl", # this must be the full URL!
     devbranch="master",
     devurl = "dev",
     push_preview=true,
@@ -37,7 +37,10 @@ folder = deploy_decision.subfolder
 println("Deploying to $folder")
 vitepress_config_file = joinpath(@__DIR__, "build", ".vitepress", "config.mts")
 config = read(vitepress_config_file, String)
-new_config = replace(config, "base: 'REPLACE_ME_WITH_DOCUMENTER_VITEPRESS_BASE_URL_WITH_TRAILING_SLASH'" => "base: '/DocumenterVitepress.jl/$(folder)$(isempty(folder) ? "" : "/")'")
+new_config = replace(
+    config, 
+    "base: 'REPLACE_ME_WITH_DOCUMENTER_VITEPRESS_BASE_URL_WITH_TRAILING_SLASH'" => "base: '/DocumenterVitepress.jl/$(folder)$(isempty(folder) ? "" : "/")'"
+)
 write(vitepress_config_file, new_config)
 
 # Build the docs using `npm` - we are assuming it's installed here!
@@ -49,7 +52,7 @@ haskey(ENV, "CI") && begin
 end
 
 deploydocs(; 
-    repo="github.com/LuxDL/DocumenterVitepress.jl",
+    repo="github.com/LuxDL/DocumenterVitepress.jl", # this must be the full URL!
     target="build/.vitepress/dist", # this is where Vitepress stores its output
     branch = "gh-pages",
     devbranch="master",

docs/src/api-examples.md

@@ -14,4 +14,6 @@ end
 ```@autodocs
 Modules = [DocumenterVitepress]
 Private = false
-```
+```
+
+See e.g. [`DocumenterVitepress.DocumenterVitepress`](@ref)

docs/src/getting_started.md

@@ -1,6 +1,11 @@
 # Getting started
 
-As a tutorial we will explain the folders and files structure used to generate this website. You could use this as a template for your project's documentation.
+As a tutorial, we will go through and explain the folder and files structure used to generate this website. You could use this as a template for your project's documentation.
+
+!!! tip
+    In general, you can copy the `docs` folder and the `.github/Documenter.yml` action file to your repo, and be pretty much good to go and edit docs as usual! 
+
+    Just remember to edit the sidebar in `docs/src/.vitepress/config.mts`.
 
 Starting at the top level, this project is organised as follows:
 
@@ -189,4 +194,4 @@ npm run docs:dev
 ```
 
 
-This should do a local deploy for your docs. See [here](https://vitepress.dev/guide/getting-started#up-and-running) to know more.
+This should do a local deploy for your docs. See [here](https://vitepress.dev/guide/getting-started#up-and-running) to know more.

docs/src/index.md

@@ -35,7 +35,21 @@ features:
 ---
 ```
 
-::: raw
-This is a Wraps in a <div class="vp-raw">
-:::
 
+<p style="margin-bottom:2cm"></p>
+
+<div class="vp-doc" style="width:60%; margin:auto">
+
+<h1> What is DocumenterVitepress.jl? </h1>
+
+DocumenterVitepress is a Markdown backend for Documenter.jl which is designed to work with the [`VitePress`](https://vitepress.dev/) site generator, which is built off `Vue.js`.  
+
+It is meant to be used in conjunction with the `vitepress` Node.js package, which is why so much customization is required!
+
+<h2> Basic usage </h2>
+
+If you copy the contents of the `docs/` directory and the `.github/Documenter.yml` file to your repo, you should be good to go and edit docs as usual! 
+
+Just remember to edit the sidebar in `docs/src/.vitepress/config.mts`.
+
+</div>

src/writer.jl

@@ -352,9 +352,16 @@ end
 # Links
 function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, link::MarkdownAST.Link, page, doc; kwargs...)
     # @infiltrate
-    print(io, "<a href=\"$(link.destination)\">")
-    render(io, mime, node, node.children, page, doc; kwargs...)
-    print(io, "</a>")
+    # For HTML links, use:
+    # print(io, "<a href=\"$(link.destination)\">")
+    # render(io, mime, node, node.children, page, doc; kwargs...)
+    # print(io, "</a>")
+    # However, we may have Markdown syntax in these links
+    # so, we use markdown link syntax which Vitepress can parse
+    # appropriately.
+    print(io, "[")
+    render(io, mime, node, node.children, page, doc; prenewline = false, kwargs...)
+    print(io, "]($(link.destination))")
 end
 # Code blocks
 function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, code::MarkdownAST.CodeBlock, page, doc; kwargs...)