docz
docz copied to clipboard
doczjs
Deployment to subdirectories after the removal of hash router
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?
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
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. 🤷♂️
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>
@pedronauck what are your thoughts? Seems like there is quite some interest in this problem, according to the number of 👍 🙂
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 :)
If you're using Docz with gitlab pages copying the index.html as 404.html is a decent workaround.
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?
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?
PS: it requires slashes on both ends, like "/mypath/", and then #1042 happens
@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
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
baseand tried both/custombase/and/custombaseon these two diffrent projects- when I then checked the
distfolder links and resources was prefixed with my custom base prefixyarn serveserved my files with my custom prefixdocz: 2.0-rc.45 OS: Windows 10 1903 Node: 10.14.1 Yarn: 1.17.2 PowerShell: 6.2.3
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)?
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.
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] avatar](https://avatars.githubusercontent.com/in/1724?v=4 "Published by a pub.dev verified publisher"){kind=small}
This issue is not stale. Our team is still stuck with 0.13.x because of it 🙏
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 !
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.
FWIW, two of the relevant Gatsby issues are open:
gatsbyjs/gatsby#14161 (reopened 3 days ago) gatsbyjs/gatsby#6945
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.
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.
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.