add arg to specify the documentation's folder, in case is not docs

[asinghvi17]

Is this an issue that has been encountered? I would have thought that the relative paths were sufficient, especially since I only ever go through doc.meta.build...

[lazarusA]

not anymore, things work for now... but, I need to provide explicitly the config.mts file, otherwise fails.

https://github.com/lazarusA/julia/tree/la/docs

Edit: more issues are showing up, but mostly formatting. I will report back later on those.

[asinghvi17]

Aha! Yeah the Julia docs would be great to test out the formatting :D

[asinghvi17]

@lazarusA Everything seems to be joinpath(doc.user.build, settings.md_output_path, ...), no explicit references to a docs folder. What exactly needs to be done here?

The package.json file does hardcode .documenter as the md_output_path or so, but that seems unrelated to this issue?

[lazarusA]

just by changing the template reading the docs and looking for information is so much better. We should try to push this whole thing a little bit more :D

[lazarusA]

yeah. You are right.

The original issue was that, if you don't provide any .json file, then it tries to copy do docs/, which it might not exist. But, things work know, maybe I should try to remove again the .vitepress folder from src and test again.

[asinghvi17]

Huh, it should never do that in theory. Maybe Documenter was run in the wrong folder? That's the only thing I can think of...

[lazarusA]

Ok, now I had removed the .vitepress folder, the build works, but it looks like it cannot install the proper node dependencies:

> docs:dev
> vitepress dev _build/html/en/.documenter

failed to start server. error:
Error: You need to install `markdown-it-mathjax3` to use math support.
    at createMarkdownRenderer (file:///Users/lalonso/node_modules/vitepress/dist/node/serve-BTRXZ1g2.js:37405:13)
    at async localSearchPlugin (file:///Users/lalonso/node_modules/vitepress/dist/node/serve-BTRXZ1g2.js:41795:14)
    at async createVitePressPlugin (file:///Users/lalonso/node_modules/vitepress/dist/node/serve-BTRXZ1g2.js:42426:5)
    at async createServer (file:///Users/lalonso/node_modules/vitepress/dist/node/serve-BTRXZ1g2.js:63811:14)

commenting out those lines for now 😄 .

[asinghvi17]

Does https://github.com/LuxDL/DocumenterVitepress.jl/pull/91 fix it?

[lazarusA]

no, it does not. Summary:

• For some reason extra Node dependencies are not being install.
• the following syntax in the config.mts menu names is not valid: 'Julia's example': (the extra ') there was a way, don't remember now.
• A lot broken id @ast things.

if you want to see what it works a the moment even this issue comment out some lines

import { defineConfig } from 'vitepress'
import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
// import mathjax3 from "markdown-it-mathjax3";
// import footnote from "markdown-it-footnote";

// https://vitepress.dev/reference/site-config
export default defineConfig({
  base: '/docs.julialang.org.git/',// TODO: replace this in makedocs!
  title: 'The Julia Language',
  description: "A VitePress Site",
  lastUpdated: true,
  cleanUrls: true,
  outDir: '../final_site', // This is required for MarkdownVitepress to work correctly...

  ignoreDeadLinks: true,

  markdown: {
    math: false,
    config(md) {
      md.use(tabsMarkdownPlugin)
      // md.use(mathjax3),
      // md.use(footnote)
    },
.
.
.

overall, I'm pretty happy with the outcome.

[lazarusA]

after cloning the repo (https://github.com/lazarusA/julia/tree/la/docs) simply doing first in the root directory:

make docs # this will build the docs.

then

cd doc

and the usual

npm run docs:dev

[asinghvi17]

ERROR: LoadError: expected package Documenter [e30172f5] to be registered

Just tried to build it, got most of the way through and then it started building HTML documentation and gave me this error.

[asinghvi17]

Ah the error here was that the path in package.json was incorrect.

[asinghvi17]

The language 'llvm' is not loaded, falling back to 'txt' for syntax highlighting. (x5)

The language 'fortran' is not loaded, falling back to 'txt' for syntax highlighting.

are probably dealbreakers for using the actual Julia docs for this, unless we manage to hack Vitepress to change its syntax highlighter to something which supports Fortran and LLVM :(

[lazarusA]

Ok. I kinda finish the Julia docs 👎🏻 . Solving https://github.com/LuxDL/DocumenterVitepress.jl/issues/101 might fix the last issue, only LibGit2 is failing and it looks related to a missing tag.

Also, I still had problems with the Node dependencies. I solved by

1. Copying the package-lock.json into doc folder and then manually doing npm i. @asinghvi17 how did you solved this?
2. For now, nav and sidebar are done manually.

You should see this:

[asinghvi17]

Whoa, that looks really cool!!

I'm hoping to tackle the sidebar + repl block issues today.

problems with the Node dependencies

I had none of these, it just worked for me...

[lazarusA]

Ah the error here was that the path in package.json was incorrect.

but, you did changed something? if I understood this correctly.

[asinghvi17]

Ah yeah I forgot :sweat_smile: I just changed the paths in the package.json to point to the cover. We should actually use npm run vitepress directly instead.