Skip to content

Commit

Permalink
docs: some adjustments
Browse files Browse the repository at this point in the history
  • Loading branch information
@pedronauck
pedronauck committed Jul 18, 2019
1 parent b8c2db1 commit 924aada
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 61 deletions.
54 changes: 14 additions & 40 deletions MIGRATION_GUIDE.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,12 @@
# Migration Guide

The [v2 release](https://github.com/pedronauck/docz/pull/950) is our biggest release in terms of changes on our core scripts.
Our bundler system was entirely modified in order to use Gatsby as default bundler and you will need to update
your code if you're coming from a previous version. It's not a big deal, but you need to follow this guide in order to get Docz running
properly on your project after the upgrade.
The [v2 release](https://github.com/pedronauck/docz/pull/950) is our biggest release in terms of changes on our core scripts. Our bundler system was entirely modified in order to use Gatsby as default bundler and you will need to update your code if you’re coming from a previous version. It’s not a big deal, but you need to follow this guide in order to get Docz running properly on your project after the upgrade.

## Gatsby as default bundler
The biggest change in the new v2 is that now our core is entirely build using Gatsby behind the scenes. This is a huge win for Docz, since now we can focus on build new features instead of handling with a lot of bundlers issues (our biggest bottleneck) and enjoy all Gatsby ecosystem.

The biggest change in the new v2 is that now our core is entirely build using Gatsby behind the scenes.
This is a huge win for Docz, since now we can focus on build new features instead of handling with
a lot of bundlers issues (our biggest bottleneck) and enjoy all Gatsby ecosystem.

So, in order to refactoring our core, we need to change a lot of things and remove others that no longer make sense.
The most expressive changes here is about the configuration for `doczrc.js` and the plugin system.
So, in order to refactoring our core, we need to change a lot of things and remove others that no longer make sense. The most expressive changes here is about the configuration for `doczrc.js` and the plugin system.

### List of removed properties from `doczrc.js`

* **`websocketHost`** ▶︎ _no longer need_
* **`websocketPort`** ︎︎︎▶︎ _no longer need_
* **`wrapper`** ▶︎ _removed_
Expand All @@ -27,7 +18,6 @@ The most expressive changes here is about the configuration for `doczrc.js` and
* **`modifyBabelRc`** ▶︎ use Gatsby [`onCreateBabelConfig`](https://www.gatsbyjs.org/docs/node-apis/#onCreateBabelConfig) hook

## New hooks for plugins

The `createPlugin` method also changed in order to fit with Gatsby now.

### List of removed/changed properties from `createPlugin()`
Expand All @@ -44,42 +34,28 @@ The `createPlugin` method also changed in order to fit with Gatsby now.
> You can have more details about then [here](https://www.gatsbyjs.org/docs/node-apis).
## `docz-theme-default` removed
The main reason that made us change our core to use Gatsby is that now it have a feature called themes. In the last major version we launched our own `gatsby-theme-docz` and this was impressive since we could use Docz inside a Gatsby project and brings a lot of new possibilites when creating a documentation.

The main reason that made me want to change our core to use Gatsby is that now it have a feature called themes.
In the last major version we launched our own `gatsby-theme-docz` and this was impressive since we could use Docz
inside a Gatsby project and brings a lot of new possibilites when creating a documentation.

So, indeed we were using Gatsby theme at all, but in the wrong way. One of the best benefits of Gatsby theme are
the feature called Component Shadowing, that's the hability to replace theme files just by creating your own file following a file naming convetion.
This is awesome and is something that people always ask for me, like: "I want just to change the head in the Docz theme".
So, indeed we were using Gatsby theme at all, but in the wrong way. One of the best benefits of Gatsby theme are the feature called Component Shadowing, that’s the ability to replace theme files just by creating your own file following a file naming convention. This is awesome and is something that people always ask for me, like: “I want just to change the head in the Docz theme”.

In order to get Docz running with component shadowing we removed `docz-theme-default` and now you don't need to install it anymore.
You can just add `docz` and your project is done
In order to get Docz running with component shadowing we removed `docz-theme-default` and now you don’t need to install it anymore. You can just add `docz` and your project is done.

Check [here]() readme for more information.
Check [here](h) readme for more information.

### Code highlight with PrismJS
In the last version of Docz we’re using Codemirror to highlight code inside `<Playground>` and code blocks. Now we are using [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) together with Theme UI.

In the last version of Docz we're using Codemirror to highlight code inside `<Playground>` and code blocks.
Now we are using [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) together with Theme UI.

Check [here]() for more information.
Check [here](h) for more information.

### New `themeConfig` properties
Another great thing launched in the newest version is the integration with the [Theme UI](https://theme-ui.com). Theme UI it’s a library for build consistent, themeable React apps based on constraint-based design principles. So, in order to integration it with our new theme, a lot of changes are made inside the `themeConfig` object.

Another great thing launched in the newest version is the integration with the [Theme UI](https://theme-ui.com).
Theme UI it's a library for build consistent, themeable React apps based on constraint-based design principles.
So, in order to integration it with our new theme, a lot of changes are made inside the `themeConfig` object.

Check [here]() for more information.
Check [here](h) for more information.

## `theme` property removed
The property used to define your Docz theme inside the `doczrc.js` was removed. But you can still create and use your own theme from scratch if you want.

The property used to define your Docz theme inside the `doczrc.js` was removed. But you can still
create and use your own theme from scratch if you want.

If you want to use your own theme, just create a file called `src/gatsby-theme-docz/index.js` in order
to use component shadowing and replace it with your new theme.
If you want to use your own theme, just create a file called `src/gatsby-theme-docz/index.js` in order to use component shadowing and replace it with your new theme.

```js
// src/gatsby-theme-docz/index.js
Expand All @@ -92,9 +68,7 @@ export default (props) => <Theme {...props} />
Check [here](https://www.docz.site/docs/creating-themes) for more information about how to create themes.

## `wrapper` property removed

The same thing happened here for the oldest `wrapper` property. Now you can wrap your entire application
by just creating a file called `src/gatsby-theme-docz/wrapper.js`
The same thing happened here for the oldest `wrapper` property. Now you can wrap your entire application by just creating a file called `src/gatsby-theme-docz/wrapper.js`

```js
// src/gatsby-theme-docz/index.js
Expand Down
31 changes: 10 additions & 21 deletions core/gatsby-theme-docz/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,7 @@ module.exports = {

### Configuration

Set your config by using `doczrc.js` file ([see all available](https://www.docz.site/docs/project-configuration)) or if you want to
set some defaults for your theme, use `options` on plugin definition:
Set your config by using `doczrc.js` file ([see all available](https://www.docz.site/docs/project-configuration)) or if you want to set some defaults for your theme, use `options` on plugin definition:

```js
// gatsby-config.js
Expand Down Expand Up @@ -53,16 +52,13 @@ export default {

### Customizing components

Components shadowing is one of the best things included in the new Gatsby theme feature, with it is possible to replace
theme files just by creating your own file following a file naming convetion.
Components shadowing is one of the best things included in the new Gatsby theme feature, with it is possible to replace theme files just by creating your own file following a file naming convention.

Example: If you're using our `gatsby-theme-docz` which has a `Header` component located at `src/components/Header/index.js`
you can override the component by creating `src/gatsby-theme-docz/components/Header/index.js`. Cool right?
Example: If you're using our `gatsby-theme-docz` which has a `Header` component located at `src/components/Header/index.js` you can override the component by creating `src/gatsby-theme-docz/components/Header/index.js`. Cool right?

### Adding your logo

So, now that you know about how component shadowing works on Gatsby themes, if you don't want to override the entire `<Header>` component
but just change your logo inside it, your can shadow the `<Logo>` component used in the header just by creating your own at `src/gatsby-theme-docz/components/Logo/index.js`
So, now that you know about how component shadowing works on Gatsby themes, if you don't want to override the entire `<Header>` component but just change your logo inside it, your can shadow the `<Logo>` component used in the header just by creating your own at `src/gatsby-theme-docz/components/Logo/index.js`

```js
// src/gatsby-theme-docz/components/Logo/index.js
Expand All @@ -76,9 +72,7 @@ Easy, right?

### Creating your own Docz theme

One of the coolest thing of Docz is that you can create your own theme if you want from scratch and use all benefits of it.
The oldest way to acomplish that is by using the `theme` property inside the `doczrc.js` file. Now, if you want to create
your own theme, just create a file located at `src/gatsby-theme-docz/index.js`
One of the coolest thing of Docz is that you can create your own theme if you want from scratch and use all benefits of it. The oldest way to acomplish that is by using the `theme` property inside the `doczrc.js` file. Now, if you want to create your own theme, just create a file located at `src/gatsby-theme-docz/index.js`

```js
import React from 'react'
Expand Down Expand Up @@ -118,8 +112,7 @@ export default theme(themeConfig)(Theme)

### Wrapping the entire app

Sometime you need to wrap your entire application in order to add some `Provider` or just to load some script.
You can do this easily inside our theme by creating a file located at `src/gatsby-theme-docz/wrapper.js`
Sometime you need to wrap your entire application in order to add some `Provider` or just to load some script. You can do this easily inside our theme by creating a file located at `src/gatsby-theme-docz/wrapper.js`

```js
// src/gatsby-theme-docz/index.js
Expand All @@ -135,10 +128,9 @@ export default ({ children }) => (

## Theme UI integrated

As default theme systeAs default theme system we are using the [Theme-UI](https://theme-ui.com/), it's a library for build consistent, themeable React apps
based on constraint-based design principles.
As default theme system we are using the [Theme-UI](https://theme-ui.com/), it's a library for build consistent, themeable React apps based on constraint-based design principles.

You can modify our based theme creating your own style, combining these modifications with the component shadowing and creating a totally differente documentation.
You can modify our based theme creating your own style, combining these modifications with the component shadowing and creating a totally different documentation.

Check our [base theme object](https://github.com/pedronauck/docz/blob/feat/gatsby/core/gatsby-theme-docz/src/theme/index.js) to see the properties.

Expand Down Expand Up @@ -174,8 +166,7 @@ export default merge(baseTheme, {

### Changing code highlight

Both code highlights shortcodes and the `<Playground>` component are using [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight the code.
If you want to modify and use another PrismJS theme, you can do that just passing a `prismTheme` property for your theme.
Both code highlights shortcodes and the `<Playground>` component are using [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight the code. If you want to modify and use another PrismJS theme, you can do that just passing a `prismTheme` property for your theme.

```js
// doczrc.js
Expand Down Expand Up @@ -226,9 +217,7 @@ export default {

## Getting data

Using our Gatsby Theme you can enjoy all our hooks to get data for your pages and also get data from Gatsby.
So, you can create isolated pages on Gatsby using gatsby pages and get data from Docz or maybe pass data
for your Docz documents using source from gatsby.
Using our Gatsby Theme you can enjoy all our hooks to get data for your pages and also get data from Gatsby. So, you can create isolated pages on Gatsby using gatsby pages and get data from Docz or maybe pass data for your Docz documents using source from gatsby.

Imagine, that you have your home page inside `/pages` and you want to show all documents parsed from Docz. You can easy get this by doing:

Expand Down

0 comments on commit 924aada

Please sign in to comment.