Merge pull request #149 from abhro/patch-1

Minor documentation patches/fixes

docs/src/code_example.md

@@ -2,13 +2,13 @@
 
 **Fonts**
 
-This package uses the JuliaMono font by default, but you can override this in CSS.  
+This package uses the JuliaMono font by default, but you can override this in CSS.
 
 This is what some common symbols look like:
 
 ```julia
 ] [ = $ ; ( @ { " ) ? . } ⊽ ⊼ ⊻ ⊋ ⊊ ⊉ ⊈ ⊇ ⊆ ≥ ≤ ≢ ≡ ≠ ≉ ≈ ∪ ∩ ∜ ∛ √ ∘ ∌
-|> /> ^ % ` ∈ 
+|> /> ^ % ` ∈
 ```
 
 ## @example
@@ -198,4 +198,4 @@ julia> 1 + 1
 julia> 1 + 1
 2
 
-```
+```

docs/src/documenter_to_vitepress_docs_example.md

@@ -1,121 +1,118 @@
 # Upgrading docs from Documenter.jl to DocumenterVitepress.jl
 
- **Assuming that your current documentation is based on Documenter.jl, you can upgrade to DocumenterVitepress.jl by following these steps:**
+**Assuming that your current documentation is based on Documenter.jl, you can upgrade to DocumenterVitepress.jl by following these steps:**
 
 Let us suppose that you are working on a package named `Example.jl` that is part of a GitHub organization named `ExampleOrg`.
 
 Then the very first step here is to update the `make.jl` file to follow the DocumenterVitepress.jl format.
 
-1. Go the the `make.jl` file in your `docs` folder and do the following necessary changes to upgrade to DocumenterVitepress.jl :
+1. Go the the `make.jl` file in your `docs` folder and do the following necessary changes to upgrade to DocumenterVitepress.jl:
 
-:::tabs
+   :::tabs
 
-== For Documenter.jl
+   == From Documenter.jl
 
    a. The `make.jl` file with `Documenter.jl` should look like this:
 
-```julia
-using Example
-using Documenter
-
-DocMeta.setdocmeta!(test, :DocTestSetup, :(using test); recursive=true)
-
-makedocs(;
-    modules = [test],
-    authors = "jay-sanjay <[email protected]> and contributors",
-    sitename = "Example.jl",
-    format = Documenter.HTML(;
-        canonical = "https://jay-sanjay.github.io/Example.jl",
-        edit_link = "main",
-        assets = String[],
-    ),
-    pages=[
-        "Home" => "index.md",
-        "Tutorials" => "tutorials.md",
-        "Api" => "api.md",
-        "Contributing" => "contributing.md"
-    ],
-)
-
-deploydocs(;
-    repo = "github.com/jay-sanjay/Example.jl",
-    devbranch = "main",
-)
-
-``` 
-
-== For DocumenterVitepress.jl
-
-  b. The same `make.jl` file with `DocumenterVitepress.jl` will look like this:
-
-```julia
-using Example
-using Documenter
-using DocumenterVitepress
-
-DocMeta.setdocmeta!(Example, :DocTestSetup, :(using Example); recursive=true)
-
-
-makedocs(;
-    modules = [Example],
-    repo = Remotes.GitHub("ExampleOrg", "Example.jl"),
-    authors = "Jay-sanjay <[email protected]>, and contributors",
-    sitename = "Example.jl",
-    format = DocumenterVitepress.MarkdownVitepress(
-        repo="https://github.com/ExampleOrg/Example.jl",
-    ),
-    pages = [
-        "Home" => "index.md",
-        "Tutorials" => "tutorials.md",
-        "Api" => "api.md",
-        "Contributing" => "contributing.md"
-    ],
-)
-
-deploydocs(;
-    repo = "github.com/ExampleOrg/Example.jl",
-    target = "build", # this is where Vitepress stores its output
-    devbranch = "main",
-    branch = "gh-pages",
-    push_preview = true
-)
-
-```
-
-:::
-
-2. Next to build new docs from docs/src 
-```sh
-$ cd docs
-docs $
-```
+   ```julia
+   using Example
+   using Documenter
+
+   DocMeta.setdocmeta!(test, :DocTestSetup, :(using test); recursive=true)
+
+   makedocs(;
+       modules = [test],
+       authors = "jay-sanjay <[email protected]> and contributors",
+       sitename = "Example.jl",
+       format = Documenter.HTML(;
+           canonical = "https://jay-sanjay.github.io/Example.jl",
+           edit_link = "main",
+           assets = String[],
+       ),
+       pages=[
+           "Home" => "index.md",
+           "Tutorials" => "tutorials.md",
+           "Api" => "api.md",
+           "Contributing" => "contributing.md"
+       ],
+   )
+
+   deploydocs(;
+       repo = "github.com/jay-sanjay/Example.jl",
+       devbranch = "main",
+   )
+   ```
+
+   == to DocumenterVitepress.jl
+
+   b. The same `make.jl` file with `DocumenterVitepress.jl` will look like this:
+
+   ```julia
+   using Example
+   using Documenter
+   using DocumenterVitepress
+
+   DocMeta.setdocmeta!(Example, :DocTestSetup, :(using Example); recursive=true)
+
+   makedocs(;
+       modules = [Example],
+       repo = Remotes.GitHub("ExampleOrg", "Example.jl"),
+       authors = "Jay-sanjay <[email protected]>, and contributors",
+       sitename = "Example.jl",
+       format = DocumenterVitepress.MarkdownVitepress(
+           repo="https://github.com/ExampleOrg/Example.jl",
+       ),
+       pages = [
+           "Home" => "index.md",
+           "Tutorials" => "tutorials.md",
+           "Api" => "api.md",
+           "Contributing" => "contributing.md"
+       ],
+   )
+
+   deploydocs(;
+       repo = "github.com/ExampleOrg/Example.jl",
+       target = "build", # this is where Vitepress stores its output
+       devbranch = "main",
+       branch = "gh-pages",
+       push_preview = true
+   )
+   ```
+
+   :::
+
+2. Next to build new docs from docs/src
+   ```sh
+   $ cd docs
+   docs $
+   ```
 3. Then, in docs start a julia session and activate a new environment.
-```sh
-docs $ julia
-julia> ]
-pkg> activate .
-```
+   ```sh
+   docs $ julia
+   julia> ]
+   pkg> activate .
+   ```
 4. Add packages as necessary. Here, we will need
 
-```julia
-pkg> add DocumenterVitepress, Documenter
-```
+   ```julia
+   pkg> add DocumenterVitepress, Documenter
+   ```
 
 5. Then run the `make.jl` file to build the documentation.
 
-```julia
-julia> include("make.jl")
-```
+   ```julia
+   julia> include("make.jl")
+   ```
 
-6. Finally hit ;  to enter in the shell mode and run:
+6. Finally hit `;` to enter in the shell mode and run:
 
-```sh
-shell> npm i
-```
-The above command shall create a folder named `node_modules` and `package-lock.json` in your docs folder.
+   ```sh
+   shell> npm i
+   ```
+   The above command shall create a folder named `node_modules` and `package-lock.json` in your docs folder.
 
 7. Next hit 'Backspace' to get back to the julia REPL and run:
-```julia
-juila> DocumenterVitepress.dev_docs("docs/build")
-```
+   ```julia
+   juila> DocumenterVitepress.dev_docs("docs/build")
+   ```
 8. Finally the live preview of your documentation at `hhttp://localhost:5173/Example.jl/` in your browser.

docs/src/getting_started.md

@@ -18,17 +18,17 @@ The section [Advanced method](@ref) describes how to get more control over your
 
 In order to develop docs locally, you can add the `clean=false` parameter to `makedocs`, and call `DocumenterVitepress.dev_docs("/path/to/docs/build")` in some other REPL.  This works with LiveServer.jl based approaches as well.  Note that the `dev_docs` call cannot be in the file that LiveServer is watching
 
-## Advanced method 
+## Advanced method
 
 If you want to customize your Vitepress build, including CSS etc., you will want to add the necessary Vitepress files to your `docs/src/.vitepress` folder.
 
 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 "Quick start"
-    In general, you can copy the `template` folder to your `docs` folder and the `.github/Documenter.yml` action file from [DocumenterVitepress.jl](https://github.com/LuxDL/DocumenterVitepress.jl) to your repo, and be pretty much good to go and edit docs as usual! 
-
+    In general, you can copy the `template` folder to your `docs` folder and the `.github/Documenter.yml` action file from [DocumenterVitepress.jl](https://github.com/LuxDL/DocumenterVitepress.jl) to your repo, and be pretty much good to go and edit docs as usual!
 
-Since we're concerned only with documentation, we'll specifically look at the `docs` folder of your Julia project or package here.  
+
+Since we're concerned only with documentation, we'll specifically look at the `docs` folder of your Julia project or package here.
 
 For more information on how to structure this, see the [Documenter.jl guide](https://documenter.juliadocs.org/stable/man/guide/)!  In this quick start, we will focus solely on how to set up DocumenterVitepress assuming you already have some basic docs (even just an `index.md` will do).
 
@@ -55,7 +55,7 @@ DocumenterVitepress/docs
             └── style.css
 ```
 
-You can ignore the rest of the files which are actually in `DocumenterVitepress/docs/src` for now - those show how to use advanced APIs, like 
+You can ignore the rest of the files which are actually in `DocumenterVitepress/docs/src` for now - those show how to use advanced APIs, like
 
 
 ## VitePress Installation
@@ -68,9 +68,9 @@ docs $
 
 ### Prerequisites
 
-DocumenterVitepress.jl is completely self-contained and installs all of its dependencies (including its own isolated version of `npm`) automatically. 
+DocumenterVitepress.jl is completely self-contained and installs all of its dependencies (including its own isolated version of `npm`) automatically.
 
-However, to view your documentation live when developing locally, you will need to install `npm` and instantiate the 
+However, to view your documentation live when developing locally, you will need to install `npm` and instantiate the
 
 VitePress can be used on its own, or be installed into an existing project. In both cases, you can install it with:
 
@@ -98,24 +98,24 @@ bun add -D vitepress
 
 To start working on your docs do the following steps:
 
-```shell
+```sh
 $ cd docs
 docs $
 ```
 
 Then, in `docs` start a julia session and activate a new environment.
 
-```shell
-docs> julia
+```sh
+docs $ julia
 julia> ]
 pkg> activate .
 ```
 
 Add packages as necessary. Here, we will need
 
 
-```shell
-pkg>  add DocumenterVitepress, Documenter
+```julia-repl
+pkg> add DocumenterVitepress, Documenter
 ```
 These packages will be used in the `make.jl` file.
 
@@ -143,8 +143,8 @@ docs/
 
 Then, run `docs/make.jl`, and in another terminal in the `docs` directory, run:
 
-```shell
-npm run docs:dev
+```sh
+docs $ npm run docs:dev
 ```
 
 This will deploy your documentation locally on a webserver.  See [here](https://vitepress.dev/guide/getting-started#up-and-running) to know more.

docs/src/index.md

@@ -20,7 +20,7 @@ hero:
     - theme: alt
       text: API
       link: /api
-      
+
 
 features:
   - icon: <img width="64" height="64" src="https://img.icons8.com/arcade/64/markdown.png" alt="markdown"/>
@@ -45,17 +45,17 @@ features:
 
 <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`.  
+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 `template/` directory into your `docs/` and the `.github/Documenter.yml` file to your repo, you should be good to go and edit docs as usual! 
+If you copy the contents of the `template/` directory into your `docs/` 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 navbar in `docs/src/.vitepress/config.mts`, if you want it to be different from the sidebar.
 
 To install a logo or favicon, you can put `logo.png` and `favicon.ico` in `docs/src/assets`, and they will be automatically detected.
 
 </div>
-```
+```

docs/src/markdown-examples.md

@@ -454,6 +454,12 @@ 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!
+
+You can also use fenced code blocks with the `math` tag for equations!
+
+```math
+\nabla^2 \Phi = \rho
+```
 ````
 
 **Output**
@@ -464,6 +470,12 @@ $$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!
 
+You can also use fenced code blocks with the `math` tag for equations!
+
+```math
+\nabla^2 \Phi = \rho
+```
+
 ## Footnotes (citation-style)
 
 **Input**

docs/src/render_pipeline.md

@@ -8,7 +8,7 @@ Documentation is therefore generated in two "stages".  These are both executed b
 
 First, the Documenter.jl pipeline is run.  It takes as input the concerned Julia modules and Markdown files, and excecutes all doctests and runnable blocks.
 
-From there, Documenter uses a plugin provided to the `format` keyword of `makedocs` to render to some viewable form.  This is where `DocumenterVitepress.jl` steps in, with the [`MarkdownVitepress`](@ref) plugin.  
+From there, Documenter uses a plugin provided to the `format` keyword of `makedocs` to render to some viewable form.  This is where `DocumenterVitepress.jl` steps in, with the [`MarkdownVitepress`](@ref) plugin.
 
 That plugin takes in the Documenter `Document` which is generated once Documenter has parsed, run and expanded all the input Markdown files, and converts it to VitePress-flavoured Markdown, which is saved in `docs/build/.documenter` by default.
 
@@ -28,7 +28,7 @@ In order to locally develop, run `npm run docs:dev` in another terminal.  This w
 
 ## Finalization
 
-Finally, if deploying, we move files around such that the only thing deployed is the rendered webpage.  
+Finally, if deploying, we move files around such that the only thing deployed is the rendered webpage.
 
 This means that the contents of `build/.documenter` are deleted, and the contents of `build/final_site` are moved into `build` proper.  This allows the complete site to be committed directly.