Docz: "base" property does not work as expected

[godmar]

When specifying a base: /mybase/ in doczrc.js, and then running yarn run docz build, the created .docz/dist folder looks like this:
```$ ls .docz/dist/
404 component---docs-resources-papers-md-fe63ff69f05fbc4ade87.js.map
404.html component---docs-resources-urls-md-18ff15bc97f33d5c99ec.js
app-166636596e5034530b76.js component---docs-resources-urls-md-18ff15bc97f33d5c99ec.js.map
app-166636596e5034530b76.js.map component---src-pages-404-js-d2f6e42ec0b240a466f0.js
chunk-map.json component---src-pages-404-js-d2f6e42ec0b240a466f0.js.map
commons-7abd6c6896e587d23041.js mybase
commons-7abd6c6896e587d23041.js.map page-data
component---docs-index-mdx-eb57cbfd78a8e941cf11.js static
component---docs-index-mdx-eb57cbfd78a8e941cf11.js.map styles.2543ff947a193d7f33b1.css
component---docs-lecture-1-lecture-1-mdx-e41e47345bd392371e15.js styles-488c87c5398088946843.js
component---docs-lecture-1-lecture-1-mdx-e41e47345bd392371e15.js.map styles-488c87c5398088946843.js.map
component---docs-lecture-2-lecture-2-mdx-0c06a42ea379446ff851.js webpack-runtime-3b441f85f0b567d235ec.js
component---docs-lecture-2-lecture-2-mdx-0c06a42ea379446ff851.js.map webpack-runtime-3b441f85f0b567d235ec.js.map
component---docs-resources-papers-md-fe63ff69f05fbc4ade87.js webpack.stats.json

The file `.docz/dist/mybase/index.html` contains references such as: 

`` that do not containmybase. There is noindex.html` file.

I was expecting to copy (or link) the .docz/dist folder to the server root directory of my Apache server and then be able to access it at https://host/mybase. This does not work with these generated files.

I would appreciate guidance whether what I am trying to do is possible with docz: build and then copy to a subfolder hanging off the server's root, with all necessary files contained in that subfolder.

[rakannimer]

Hey @godmar this should be fixed by 2.0.0-rc.40.

docz now uses --prefixPaths from Gatsby when base is provided in doczrc.js

[ronaklalwaniii]

Hi, I am also facing this same issue. Till when version2.0.0-rc.40 will be released?. I have to deploy my docs Asap.

[rakannimer]

Hey @ronaklalwaniii

2.0.0-rc.40 is already released.

You can do yarn add docz@next to update.

[ronaklalwaniii]

@rakannimer thanks for the quick reply. I am facing some console errors after the update. Can you please check image and tell me if this is how I am supposed to add the base path and this is how dist folder is supposed to be.

.

[rakannimer]

The way you're setting base seems correct.

Did you try deleting .docz and node_modules and re-installing docz ?

[godmar]

Doesn't work for me, either, even with a fully wiped node_modules and .docz.
Although the top page comes up, plenty of references are not prefixed, and links aren't prefixed either.
You can look at it yourself: https://theta.cs.vt.edu/cpp2019/

[rakannimer]

Ok thanks for the link !

@Dangoo do you think our recent change to the route field in Entry is at fault ?

The files are there if you append the slug to the base argument so prefixPaths is working as expected.

For example https://theta.cs.vt.edu/cpp2019/docs-lecture1-lecture-1/ exists but it's being linked to as https://theta.cs.vt.edu/docs-lecture1-lecture-1/

[Dangoo]

@rakannimer
Actually I have tested it myself with a github page (sadly not allowed to share yet) and there the paths are prefixed correctly.

@godmar can you reproduce the hosted behavior locally as well by running the following?

$ docz build
# $ gatsby build --prefixPaths
# ...
# ✨  Done in 30.35s.
$ docz serve
# $ gatsby serve --prefixPaths
# info gatsby serve running at: http://localhost:9000/cpp2019/

[godmar]

I don't have a globally installed docz. If I run

$ yarn docz build
yarn run v1.17.3
warning package.json: No license field
$ /home/gback/cppclass2019/node_modules/.bin/docz build
warning package.json: No license field
error Command "build" not found.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
✖  error     Error: ENOENT: no such file or directory, stat '/home/gback/cppclass2019/.docz/public' 
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

I'm using docz-@^2.0.0-rc.40 - does it have a build command?

[Dangoo]

@godmar
try using it either as predefined script from package.json or prefixing it with npx

$ npx docz build
$ npx docz serve

does it have a build command?

Yes, it does. In fact, that’s the way how it should be used with gatsby under the hood.

1. docz build creates a static version of your styleguide through gatsby, inkl. bundling your components and a runtime script 📦
2. you can run docz serve to emulate a webserver or host the build output from a (static) webserver afterwards 🚀

Have a look here:
https://www.docz.site/docs/project-configuration#dest

[godmar]

Edit: see comment below for an explanation of what was happening here.

Same result with npx.

$ npx docz serve
yarn run v1.17.3
warning package.json: No license field
error Command "serve" not found.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

The documentation says to run docz dev. When I do this it tries to build the site, but then fails with:

* ../components/Notice in ./src/gatsby-theme-docz/index.js
✖ ｢wdm｣:
ERROR in ./src/gatsby-theme-docz/index.js
Module not found: Error: Can't resolve '../components/Notice' in '/home/gback/cppclass2/.docz/src/gatsby-theme-docz'
 @ ./src/gatsby-theme-docz/index.js 1:2364-2405 1:2540-2546
 @ ../node_modules/gatsby-theme-docz/src/base/Layout.js
 @ ../docs/index.mdx
 @ ./.cache/sync-requires.js
 @ ./.cache/app.js

Here, paths are screwed up. I am overriding gatsby-theme-docz/index.js as described here - all I do is add one more built-in component so I don't have to import it, see here

I have been successfully using yarn run gatsby serve for development and yarn run gatsby build for building.

BTW, when I use yarn run gatsby develop the path prefix is not respected.

I am a bit confused regarding whether to use the docz commands or simply the docz theme in Gatsby. I felt it's safer to do the latter, so I followed these instructions and not these. That said, IIRC, even with the latter, the base stuff did not work.

[godmar]

So - why does npx docz serve print yarn ...?
I think docz is running, but here you are running yarn, presumably inside the .docz directory.
This failed for me, presumably because the .docz directory is in an undefined state.

If I wipe that directory and start over, I observe the following:

(a) when using yarn run gatsby develop I see the site served correctly at http://localhost:8000/cpp2019/

(b) when using yarn run gatsby build I am getting the results presented at the top of this issue.

(c) when running yarn run docz build after trying the commands in (a) and (b), I get the Command "build" not found error. This is, presumably, because the .docz directory contains only a folder app and no package.json file.

(d) Now I wipe my .docz folder, and run yarn run docz build again. I see a message

✅    Docz is ready to go 

💻    yarn docz dev
⛏    yarn docz build
👀    yarn docz serve

but this build eventually fails with:

TypeError: Cannot read property 'replace' of undefined

  - render-page.js:19164 Code
    /home/gback/cppclass2/.docz/public/render-page.js:19164:37

This is an error I have previously tracked down to your Code component; if no language is specified in a triple backquote section, docz fails. This is why I had to override your component like so:

--- node_modules/gatsby-theme-docz/src/components/Code/index.js 2019-09-04 11:26:27.155000000 -0400
+++ src/gatsby-theme-docz/components/Code/index.js  2019-09-05 09:15:05.869936223 -0400
@@ -5,8 +5,8 @@

 import { usePrismTheme } from '~utils/theme'

-export const Code = ({ children, className: outerClassName }) => {
-  const [language] = outerClassName.replace(/language-/, '').split(' ')
+export const Code = ({ children, className: outerClassName, ...rest }) => {
+  const [language] = outerClassName ? outerClassName.replace(/language-/, '').split(' ') : ['text']
   const theme = usePrismTheme()

   return (

but when running yarn run docz build my overridden components aren't picked up. (This is presumably expected since I am using the gatsby-theme-docz so my application is a gatsby with a docz theme, correct?)

[godmar]

ps: so there seems to be differences in behavior when using docz via the docz command vs. using it via gatsby + gatsby-theme-docz. I know too little about either system to tell which one I should be using. Intuitively, I felt more comfortable with the latter, hoping that I would then have gatsby + docz rather than docz with gatsby hidden inside it. But I may be wrong - I and perhaps others in the community could benefit from clarification which of these 2 approaches are to be preferred or what, in general, the trade-offs are. Thank you.

[ronaklalwaniii]

@rakannimer after hours of trying, removing extra slash at the end of base worked for me.

[godmar]

@ronaklalwaniii can you share if you're using docz or the gatsby-theme-docz setup?

[ronaklalwaniii]

@godmar, I am using gatsby-theme-docz setup.

[rubencustodio]

I am now getting everything to work correctly except when I set the base, it actually adds it twice resulting in my sidebar links being /styleguide/styleguide/Component.

[jesperorb]

What's the specific case/cases when this fails? Trying to reproduce.

1. I created two new project with:

npx create-docz-app my-docz-app

1. then I edited base and tried both /custombase/ and /custombase on these two diffrent projects
2. when I then checked the dist folder links and resources was prefixed with my custom base prefix
3. yarn serve served my files with my custom prefix

---

docz: 2.0-rc.45
OS: Windows 10 1903
Node: 10.14.1
Yarn: 1.17.2
PowerShell: 6.2.3

[rubencustodio]

I was able to get it to work by downgrading docz to 2.0.0-rc.39.

My doczrc.js looks like this

export default {
  base: '/guides/',
  title: 'Guide',
  src: './',
  dest: '../public/guides/',
  typescript: true,
  debug: true,
}

[rubencustodio]

Any updates on this? I would really love to update the version number to latest...

[rakannimer]

Hey @rubencustodio

Any chance you can provide a repo with a small repro of the problem ?

EDIT: I was able to repro, fixing.

[rakannimer]

I think this should be solved with the latest docz release candidate 2.0.0-rc.66 . Could you give it a try ?

You can also see a working example here : https://github.com/doczjs/docz/tree/master/examples/custom-base-path

If you're using docz as a theme in a gatsby site then you can just pass --prefixPaths /my-path/ to gatsby build and gatsby serve and it should work as expected.

[drbuys]

2.0.0-rc.66 fixed this for me. Thanks 👍

[crazyll]

"docz": "^2.3.1"

npx docz serve

 docz-app@ serve /Users/Documents/webApp/xxxxxx/packages/mobile-ui-doc/.docz
 gatsby serve "--port" "3001" "--host" "localhost"

⠀
You can now view docz-app in the browser.
⠀
  http://localhost:3001/

docz serve missed --prefix-paths option.