pedronauck / gatsby-starter-docz

📝 Gatsby starter with Docz and a blog for your documentation

Gatsby's Docz starter

👀 Look at the Demo

Start to write your library documentation or your design system with Docz and Gatsby in a very simple way with this starter. It's included in it some basic setup using gatsby-theme-docz and a blog using Gatsby features.

🚀 Quick start

1. Create a Gatsby site.

   Use the Gatsby CLI to create a new site, specifying this starter.

   # create a new Gatsby site using the Docz starter
   gatsby new coolest-library https://github.com/pedronauck/gatsby-starter-docz

2. Start developing.

   Navigate into your new site’s directory and start it up.

   cd coolest-library
   gatsby develop

3. Open the source code and start editing!

   Your site is now running at http://localhost:8000 and your documentation is on http://localhost:8000/docs

   Note: You'll also see a second link: http://localhost:8000/___graphql. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the Gatsby tutorial.

   Open the coolest-library directory in your code editor of choice and edit both src/pages, /blog or /docs. Save your changes, add some posts or new documents and the browser will update in real time!

🧐 What's inside?

A quick look at the top-level files and directories you'll see in a Gatsby project.

.
├── node_modules
├── blog
├── docs
├── src
├── .gitignore
├── .prettierrc
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── LICENSE
├── package-lock.json
├── package.json
└── README.md

1. /node_modules: This directory contains all of the modules of code that your project depends on (npm packages) are automatically installed.

2. /blog: This directory will contain all your blog posts writted using mdx.

3. /docs: This directory it's just an example how you can add documentation for Docz. So, instead of have just one directory with your documentation, you can put wherever you want your documents since Docz don't need to have a specific folder for that. So, by default inside the doczrc.js configuration file, we're ignoring .mdx inside blog/ folder.

4. /src: This directory will contain all of the code related to what you will see on the front-end of your site (what you see in the browser) such as your site header or a page template. src is a convention for “source code”.

5. .gitignore: This file tells git which files it should not track / not maintain a version history for.

6. .prettierrc: This is a configuration file for Prettier. Prettier is a tool to help keep the formatting of your code consistent.

7. doczrc.js: This is the Docz configuration file. Inside it you will define all configuration related to Docz and how you want to modify it.

8. gatsby-browser.js: This file is where Gatsby expects to find any usage of the Gatsby browser APIs (if any). These allow customization/extension of default Gatsby settings affecting the browser.

9. gatsby-config.js: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. (Check out the config docs for more detail).

10. gatsby-node.js: This file is where Gatsby expects to find any usage of the Gatsby Node APIs (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process.

11. gatsby-ssr.js: This file is where Gatsby expects to find any usage of the Gatsby server-side rendering APIs (if any). These allow customization of default Gatsby settings affecting server-side rendering.

12. LICENSE: Gatsby is licensed under the MIT license.

13. package-lock.json (See package.json below, first). This is an automatically generated file based on the exact versions of your npm dependencies that were installed for your project. (You won’t change this file directly).

14. package.json: A manifest file for Node.js projects, which includes things like metadata (the project’s name, author, etc). This manifest is how npm knows which packages to install for your project.

15. README.md: A text file containing useful reference information about your project.

🎓 Learning Gatsby and Docz

Looking for more guidance? Full documentation for Docz lives on the website and Gatsby also on this website. Here are some places to start on Gatsby:

• For most developers, we recommend starting with our in-depth tutorial for creating a site with Gatsby. It starts with zero assumptions about your level of ability and walks through every step of the process.

• To dive straight into code samples, head to our documentation. In particular, check out the Guides, API Reference, and Advanced Tutorials sections in the sidebar.

💫 Deploy

gatsby-starter-docz's Issues

Error: The "path" argument must be of type string. Received type undefined

On my first run gatsby develop it threw an error: Error: Cannot find module 'to-style', I followed this approach and then it threw an GraphQL error: Multiple "root" queries found: "DefaultSEOQuery" and "DefaultSEOQuery". Only the first ("DefaultSEOQuery") will be registered.. Following this approach I upgraded my gatsby-theme-docz to gatsby-theme-docz@next. And now it threw another error below that I wasn't able to solve yet.

$ gatsby develop
warn Configuring yargs through package.json is deprecated and will be removed in
⠙ open and validate gatsby-configs

 ERROR

UNHANDLED REJECTION The "path" argument must be of type string. Received type undefined



  Error: TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type s  tring. Received type undefined

  - validators.js:112 validateString
    internal/validators.js:112:11

  - gatsby-config.js:58 module.exports
    [coolest-library]/[gatsby-theme-docz]/gatsby-config.js:58:22

  - index.js:73 resolveTheme
    [coolest-library]/[gatsby]/dist/bootstrap/load-themes/index.js:73:19

  - index.js:138
    [coolest-library]/[gatsby]/dist/bootstrap/load-themes/index.js:138:22

⠙ open and validate gatsby-configs

Anyone has any suggestions? Huge thanks!

"Error: Cannot find module 'to-style'" after attempting to "gatsby develop" cloned repo

Hi.
I cloned the repo using
gatsby new coolest-library https://github.com/pedronauck/gatsby-starter-docz
but I can't "gatsby develop" it, it shows an error. I followed instructions 100% so I guess this must be some kind of bug.

Here's the full printout:

$ gatsby develop
Something is already running at port 8000
Would you like to run the app at another port instead? [Y/n] y
Configuring yargs through package.json is deprecated and will be removed in the next major release, please use the JS API instead.
success open and validate gatsby-configs - 4.219 s

 ERROR

Error in "C:\Z\Poslovno\Web Dev\coolest-library\node_modules\gatsby-mdx\gatsby-node.js": Cannot find module 'to-style'



  Error: Cannot find module 'to-style'

  - loader.js:580 Function.Module._resolveFilename
    internal/modules/cjs/loader.js:580:15

  - loader.js:506 Function.Module._load
    internal/modules/cjs/loader.js:506:25

  - loader.js:636 Module.require
    internal/modules/cjs/loader.js:636:17

  - v8-compile-cache.js:159 require
    [coolest-library]/[v8-compile-cache]/v8-compile-cache.js:159:20

  - babel-plugin-html-attr-to-jsx-attr.js:2 Object.<anonymous>
    [coolest-library]/[gatsby-mdx]/utils/babel-plugin-html-attr-to-jsx-attr.js:2    :23

  - v8-compile-cache.js:178 Module._compile
    [coolest-library]/[v8-compile-cache]/v8-compile-cache.js:178:30

  - loader.js:699 Object.Module._extensions..js
    internal/modules/cjs/loader.js:699:10

  - loader.js:598 Module.load
    internal/modules/cjs/loader.js:598:32

  - loader.js:537 tryModuleLoad
    internal/modules/cjs/loader.js:537:12

  - loader.js:529 Function.Module._load
    internal/modules/cjs/loader.js:529:3

  - loader.js:636 Module.require
    internal/modules/cjs/loader.js:636:17

  - v8-compile-cache.js:159 require
    [coolest-library]/[v8-compile-cache]/v8-compile-cache.js:159:20

  - gen-mdx.js:9 Object.<anonymous>
    [coolest-library]/[gatsby-mdx]/utils/gen-mdx.js:9:27

  - v8-compile-cache.js:178 Module._compile
    [coolest-library]/[v8-compile-cache]/v8-compile-cache.js:178:30

  - loader.js:699 Object.Module._extensions..js
    internal/modules/cjs/loader.js:699:10

  - loader.js:598 Module.load
    internal/modules/cjs/loader.js:598:32

using mdx in /blog

Ok, this is a newbie question. The documentation says that I can use mdx for the blog.

How exactly do I do that? If I place an index.mdx instead of index.md in a subdirectory of blog, it's not picked up. If I use index.md and add 'import { }' statements, they are rendered and not processed.

How do I make use of mdx in the /blog directory?

Unable to build project with a clean install following quickstart

Description

Unable to build project and receive the following error:

Error: You must provide the URL of lib/mappings.wasm by calling SourceMapConsumer.initialize({ 'lib/mappings.wasm': ... }) before using SourceMapConsumer

Steps to reproduce

Follow exact steps in the quickstart guide. I.e. a clean build.

Environment

Node version: v10.15.3
OS: MacOS Mojave 10.14.3

Extra information

Seems related to this in the gatsbyjs repo:
gatsbyjs/gatsby#13641

Cannot set `src` field in Docz configuration file

Hi, Thanks for the starter kit, it works smoothly.

Recently I met a problem that all the docs in blog file come into the my docs page. So I tried to add the src field in .doczrc, but I got the error like the following:

The plugin "gatsby-theme-docz" created a page with a component that doesn't exist. Missing component is /Users/myusername/Projects/coolest-library/Button.mdx

I even tried a new repository, the error comes once I add the src field.

I have checked the createPage file in gatsby-theme-docz, it seems they do not get options from .doczrc, the related code here: https://github.com/pedronauck/docz/blob/master/core/gatsby-theme-docz/src/node/createPages.js#L28-L37

I updated all the related dependencies to latest one, but the problem has not been solved, so I guess it could be some binding problem with Docz and Gatsby, so I think here it the right place to ask the problem.

Error with Layout.tpl.js and GraphQL error - Duplicated documents: - DefaultSEOQuery

This is the error I get when I follow the install guide.

 ERROR 

There was a problem parsing "/home/user/project_dir/node_modules/gatsby-theme-docz/templates/Layout.tpl.js"; any GraphQL fragments or queries in this file were not processed.
This may indicate a syntax error in the code, or it may be a file type that Gatsby does not know how to parse.


 ERROR #85901  GRAPHQL

There was an error in your GraphQL query:

Error: RelayParser: Encountered duplicate defintitions for one or more documents: each document must have a unique name. Duplicated documents:
- DefaultSEOQuery

Any idea how to fix that?

/docs and /docs/button pages broken

After a fresh install and migrating to gatsby-theme-docz@next, the "/docs" page renders a development 404 page

The "/docs-button" page is also broken with those errors :

Uncaught TypeError: Object(...) is not a function
    at Header (index.js:1)
    at renderWithHooks (react-dom.development.js:16319)
    at mountIndeterminateComponent (react-dom.development.js:18734)
    at beginWork$1 (react-dom.development.js:20083)
    at HTMLUnknownElement.callCallback (react-dom.development.js:363)
    at Object.invokeGuardedCallbackDev (react-dom.development.js:412)
    at invokeGuardedCallback (react-dom.development.js:467)
    at beginWork$$1 (react-dom.development.js:25729)
    at performUnitOfWork (react-dom.development.js:24637)
    at workLoopSync (react-dom.development.js:24613)
    at performSyncWorkOnRoot (react-dom.development.js:24181)
    at react-dom.development.js:12239
    at unstable_runWithPriority (scheduler.development.js:815)
    at runWithPriority$2 (react-dom.development.js:12189)
    at flushSyncCallbackQueueImpl (react-dom.development.js:12234)
    at flushSyncCallbackQueue (react-dom.development.js:12222)
    at scheduleUpdateOnFiber (react-dom.development.js:23600)
    at Object.enqueueSetState (react-dom.development.js:14030)
    at LocationProvider../node_modules/react/cjs/react.development.js.Component.setState (react.development.js:335)
    at index.js:104