Docz: Allow deploying on GitHub pages

[danburzo]

Feature Request

I'm not sure if it's something for the default theme or the core package, but:

Is your feature request related to a problem? Please describe.

It's currently impossible (I think) to deploy Docz to GitHub Pages, since the latter has now way of working with routes.

Describe the solution you'd like

Either allow using hash routes, such as: https://username.github.io/project/#section (The way Storybook does it)

or, ideally, generate individual pages for all the sections with SSR.

Describe alternatives you've considered

I'm currently investigating whether there's something one can do about it in the current Docz version.

Teachability, Documentation, Adoption, Migration Strategy

The hash-route will (probably) manifest itself in a config option that is opt-in. Not sure yet about SSR.

[danburzo]

Okay, for the hash routing solution, I guess a possible fix is to allow using either BrowserRouter or HashRouter here:
https://github.com/pedronauck/docz/blob/9284692fdc12f8be5d2bcccf3fcb141b142660d2/packages/docz/src/theme.tsx#L80

This may work well by exposing it as an option for themes?, e.g.:

diff --git a/packages/docz/src/theme.tsx b/packages/docz/src/theme.tsx
index c94a1da..c3d42b2 100644
--- a/packages/docz/src/theme.tsx
+++ b/packages/docz/src/theme.tsx
@@ -56,9 +56,11 @@ const initialContext: DataContext = {
 export const dataContext = React.createContext(initialContext)

 const DefaultWrapper: SFC = ({ children }) => <Fragment>{children}</Fragment>
+const DefaultRouter: CT = BrowserRouter;

 export interface ThemeProps extends DataContext {
-  wrapper?: CT
+  wrapper?: CT,
+  router?: CT,
   children(WrappedComponent: CT): JSX.Element
 }

@@ -68,6 +70,7 @@ export function theme(defaultConfig?: ThemeConfig): ThemeReturn {
   return WrappedComponent => {
     const Theme: CT<ThemeProps> = ({
       wrapper: Wrapper = DefaultWrapper,
+      router: Router = DefaultRouter,
       entries,
       imports,
       config = {},
@@ -77,11 +80,11 @@ export function theme(defaultConfig?: ThemeConfig): ThemeReturn {

       return (
         <dataContext.Provider value={value}>
-          <BrowserRouter basename={BASE_URL}>
+          <Router basename={BASE_URL}>
             <Wrapper>
               <WrappedComponent />
             </Wrapper>
-          </BrowserRouter>
+          </Router>
         </dataContext.Provider>
       )
     }

[pedronauck]

@danburzo you can deploy the site on github pages by changing the base property on project configuration: https://www.docz.site/documentation/project-configuration#basic-config

Did you try this?

[danburzo]

Sorry, I realize now my initial message was not very clear.

I was, indeed, able to deploy Docz to Github Pages by using the base property (site here). However, if you go to a specific component's page, refreshing the page will result in HTTP 404.

Which brings me to the reason I opened this issue: I think it's important that Docz pages be hostable on Github Pages. create-react-app has this to say about routing and Github Pages:

You could switch from using HTML5 history API to routing with hashes. [...]
Alternatively, you can use a trick to teach GitHub Pages to handle 404 by redirecting to your index.html page with a special redirect parameter. [...]

To me, the first option is the more reasonable one: switch from BrowserRouter to HashRouter.

Of course, static individual pages would be _ideal_, but I realize it's much more work involved.

[pedronauck]

Sure, now I got the message! Of course, I think that can be a good solution change the router type, but I think that is better use some property on configuration for that, like:

//doczrc.js
export default {
  hashRouter: true
}

Because is kinda dangerous pass a Router component to components!

[danburzo]

Sounds good! I'd make a PR, but I haven't used TypeScript before and I'm a bit out of my league here as to how things work :)