Docz: Deployment to subdirectories after the removal of hash router

Created on 4 Apr 2019 · 31Comments · Source: doczjs/docz

Question

After seeing that the hash router is being removed from v1, I'm wondering if serving built doczs is still possible from subdirectories. This is critical for targets like github pages, where the root of a doc is at https://username.gitub.io/project/.

GitHub pages is not the only use case here. At our company, we have a documentation portal to which a bunch of independent docs are deployed, doczs included. Their roots are at https://docs.internal/my-doc/ (the subdirectory name is not known at build time). With the hash router, internal navigation in docz works, but I'm not sure if this still the case in v1.

If with github pages, there is some freedom to re-deploy docs to another static website hoster, in our case we can't migrate away from or change the internal documentation portal structure. Switching to URLs like https://my-doc-name.docs.internal/ so that the root path was always / is simply not possible.

It'd be ideal if the base URL could be defined like ., same as in CRA. Knowing the target path is not always possible, especially if a build is first previewed, say, at https://example.com/docs/prs/my-doc/42/ and is then redeployed to https://example.com/docs/my-doc/.

What are the future options for those who want to deploy a docz instance to a subdirectory?

bug v2

Source

kachkaev

👍39

Most helpful comment

I've come across an extremely simple solution to this using https://www.npmjs.com/package/hash-source

It's a two line change to Docz to switch it to use hash router, which means we're talking maybe 5 lines to make it support either via the deprecated hashRouter config option:

+ import createHashSource from 'hash-source';
...
- const history = useMemo(() => createHistory(window), []);
+ const history = useMemo(() => createHistory(createHashSource), []);

Big high-five to anyone that wants to contribute this back into Docz :)

jonnyasmar on 21 May 2019

👍11

All 31 comments

I would like to remain hash router as in my company we are only able to deploy to a web server which we cannot change there configurations

huchenme on 11 Apr 2019

👍9

From what I gather we're getting steered towards using the Gatsby theme version but it's very unclear if you lose anything by doing so or why you wouldn't just go full Gatsby at that point. 🤷‍♂️

wldcordeiro on 15 Apr 2019

Provide a 404.html at the root folder to your gh-pages branch would help:

<!DOCTYPE html>
<html lang="en">
  <head>
    <script>
      location.pathname = '/your project sub folder/'
    </script>
  </head>
  <body></body>
</html>

leftstick on 18 Apr 2019

👎2

@pedronauck what are your thoughts? Seems like there is quite some interest in this problem, according to the number of 👍 🙂

kachkaev on 25 Apr 2019

I've come across an extremely simple solution to this using https://www.npmjs.com/package/hash-source

It's a two line change to Docz to switch it to use hash router, which means we're talking maybe 5 lines to make it support either via the deprecated hashRouter config option:

+ import createHashSource from 'hash-source';
...
- const history = useMemo(() => createHistory(window), []);
+ const history = useMemo(() => createHistory(createHashSource), []);

Big high-five to anyone that wants to contribute this back into Docz :)

jonnyasmar on 21 May 2019

👍11

Thanks @jonnyasmar, what do you think @pedronauck ?

huchenme on 21 May 2019

If you're using Docz with gitlab pages copying the index.html as 404.html is a decent workaround.

wldcordeiro on 21 May 2019

👍2

Same here, we can only use hashes

giulianok on 27 Jun 2019

Great news on seeing 2.0.0-rc.1 in releases! 🎉
@pedronauck given the migration to Gatsby, is the app now deployable to an arbitrary directory? Will routing work?

kachkaev on 19 Jul 2019

👀2

Oops. Does this work? I had naively assumed that simply putting

   base: "/mypath"

into doczrc.js would work.

However, it does not - the links in the sidebar go to /slug instead of /mypath/slug.

Should this work? Should I file an issue?

godmar on 29 Aug 2019

PS: it requires slashes on both ends, like "/mypath/", and then #1042 happens

godmar on 29 Aug 2019

@rakannimer what is the reason this issue get closed?

huchenme on 2 Oct 2019

@huchenme, what do you mean ?

rakannimer on 2 Oct 2019

@rakannimer Glad to see that this issue was labelled with , which brings hope 🙏

Does hash routing still require any input from docz team or can developers get it working in 2.0.0-rc.×× already because of Gatsby under the hood?

Asking because our team experiences some low-level bug in [email protected], which happenned after we bumped seemingly unrelated dependencies. This makes me wondering if I should dive into investigating it or just upgrade to the latest v2 release candidate. Switching to v1 is not an option for our company because hash routing is not supported there.

kachkaev on 9 Oct 2019

@kachkaev

I replied the following in related tread that also had problems with deploying to subdir but has yet to get a response there. We have made changes to how the base-property is used since the replies above. So it should work, at least it worked when i did the following:
https://github.com/doczjs/docz/issues/1042#issuecomment-536294316

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

I created two new project with:
npx create-docz-app my-docz-app
then I edited base and tried both /custombase/ and /custombase on these two diffrent projects

when I then checked the dist folder links and resources was prefixed with my custom base prefix

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

jesperorb on 9 Oct 2019

Defining a specific base at build time is limiting, unless it can be equal to . like in CRA. In our CI/CD pipelines, we do not know in advance where a specific docz artifact will be deployed to. The same artifact can go to /preview/my-doc/pullrequest1234/ and /my-doc/. Besides, a developer might want to build and look at it locally just at http://localhost:5000/.

Have you tried setting base to .? How does it work for you, especially when your docz pages have paths like components/Blah (with a slash within them)?

kachkaev on 9 Oct 2019

Ah I see, haven't tried that. docz is using --prefix-paths internally for it so it is handled by that then if it is handled.

jesperorb on 9 Oct 2019

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

stale[bot] on 8 Dec 2019

This issue is not stale. Our team is still stuck with 0.13.x because of it 🙏

kachkaev on 8 Dec 2019

👍3

I would love to get this fixed as it's reasonable to allow static builds to be deployed anywhere, but I'm currently out of ideas on how to do it.

Using a hash router is not going to be possible because Gatsby uses @reach/router and it seems like they really don't want to add hash routing support out of the box.

The other option is to use "relative paths" like CRA, but it looks like all gatsby issues requesting it have been abandoned :
https://github.com/gatsbyjs/gatsby/issues/10086
https://github.com/gatsbyjs/gatsby/issues/14161
https://github.com/gatsbyjs/gatsby/issues/2467
https://github.com/gatsbyjs/gatsby/issues/6945

We could maybe open a new one and a PR to go with it ?

Have you tried setting base to . ?

Gatsby treats it as a normal string and prepends urls with /./

I'm open to ideas, suggestions and of course PRs !

rakannimer on 11 Dec 2019

👀2 ❤1

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

stale[bot] on 9 Feb 2020

not stale :(

kachkaev on 9 Feb 2020

FWIW, two of the relevant Gatsby issues are open:

gatsbyjs/gatsby#14161 (reopened 3 days ago)
gatsbyjs/gatsby#6945

estaub on 9 Feb 2020

👀1

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

stale[bot] on 9 Apr 2020

not stale, very topical (although blocked by upstream) 😔

kachkaev on 9 Apr 2020

up. it is problem very topical.

ghost on 1 May 2020

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

stale[bot] on 30 Jun 2020

not stale

kachkaev on 2 Jul 2020

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

stale[bot] on 1 Sep 2020

not stale

kachkaev on 1 Sep 2020

In my company, We only have a single server for docs。We share a domain，such as http://docs.company.com。We can only use subdirectory to isolate different teams。yes subdirectory