# Merging GraphQL and Dgraph docs **URL:** \ **Category:** Dev\ **Tags:** area:documentation\ **Created:** [August 7, 2020, 7:45am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282 "2020-08-07T07:45:21Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![pawan](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/pawan/32/1946_2.png) [@pawan](https://discuss.dgraph.io/u/pawan)\ **Post date:** [August 7, 2020, 7:45am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/1 "2020-08-07T07:45:21Z")
We aim to merge [docs.dgraph.io](http://docs.dgraph.io) and [graphql.dgraph.io](http://graphql.dgraph.io) into a single site with a single repo. Since Dgraph docs use Hugo and GraphQL docs use GatsbyJS, we have some decisions to make here. The easiest approach seems to be to move the GraphQL docs to Hugo and merge them with Dgraph docs. * * * Pros - This would be easier to do as we just have to port over the GraphQL docs to the Dgraph repo along with other docs. - Hugo theme already has things like runnable, Algolia search etc. Cons - We lose the cool design that we have in GraphQL docs for now until it is reworked upon later. - We can’t use GatsbyJS which apparently seems to be more customizable than Hugo as per @vardhanapoorv. The other options are to move the Dgraph docs to the GraphQL docs. That seems like more work initially where we first need to have additional things like runnable, search etc over first and then we can migrate the docs. A bigger question here is that is GatsbyJS significantly better than the Hugo theme for us to go in this direction? CC: @michaelcompton @vardhanapoorv who would know more about this. @vvbalaji ## UPDATE - Based on the conversation with @gja the aim right now is just to have a landing page for docs which links to Dgraph, GraphQL, Slash, Client etc docs and to get all of these docs under the same domain. That should be easier to do. Eventually, we’ll use the same framework for all the docs but that is a long term solution. We’ll just have to be careful to make sure that the old links still work. ---
**Author:** ![mrjn](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/mrjn/32/775_2.png) [@mrjn](https://discuss.dgraph.io/u/mrjn)\ **Post date:** [August 7, 2020, 1:49pm UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/2 "2020-08-07T13:49:33Z")
Just to clarify, I never commented on the two systems being kept separate (seeing some conversations between you and Tejas). In fact, I’m just learning that GraphQL docs are written via Gatsby. If I had known earlier, I would not have approved another system, or at least questioned that decision very hard. Let’s talk today about this. ---
**Author:** ![pawan](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/pawan/32/1946_2.png) [@pawan](https://discuss.dgraph.io/u/pawan)\ **Post date:** [August 11, 2020, 11:48am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/3 "2020-08-11T11:48:29Z")
Had a chat with @vardhanapoorv about this. This is what we have decided. The GraphQL docs would be available at [https://dgraph.io/docs/graphql/](https://dgraph.io/docs/graphql/) similar to how the badger docs are at [Badgerdb documentation —](https://dgraph.io/docs/badger/). The other alternative would have been to have GraphQL as section along with other sections in the left side menu along with Mutations, Query Language etc. at [https://dgraph.io/docs/](https://dgraph.io/docs/). We have chosen the first approach because of the following reasons: - Current docs only support 2 level of nesting but we need three level nesting. See [https://graphql.dgraph.io/doc/schema/types](https://graphql.dgraph.io/doc/schema/types) for example. - GraphQL docs and its different sections should stand out. It should not just be another section along with Mutations, Query language and GraphQL± as that would confuse the users. - Since GraphQL is only available from 20.03, we don’t need to have a version selector for all the older versions for it. Tasks to do - Migrate Documentation reference, Todo tutorial and Slash docs to a Hugo based theme. - Figure out which directory to keep the docs in, they can lie in a new folder inside the Dgraph repo for now and can be moved to a different repo if required later. - Redirects should work properly. Coordinate with @zhenni about that before making them live. - Have support for versions 20.03.0, 20.07.0 and master. - Deploy and make them go live @vardhanapoorv is also going to share some screenshots of some initial pages by end of day today once he is done porting them. ---
**Author:** ![vardhanapoorv](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/vardhanapoorv/32/2441_2.png) [@vardhanapoorv](https://discuss.dgraph.io/u/vardhanapoorv)\ **Post date:** [August 11, 2020, 2:53pm UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/4 "2020-08-11T14:53:35Z")
Current state ![Screenshot 2020-08-11 at 7.49.40 PM](https://canada1.discourse-cdn.com/flex007/uploads/dgraph/original/2X/6/6312da3617776fafad74ae248e7ca7965b93a9bc.png) ![Screenshot 2020-08-11 at 8.19.44 PM](https://canada1.discourse-cdn.com/flex007/uploads/dgraph/original/2X/1/1b8aceaa01636ed09eec180244a94d9b73958916.png) ---
**Author:** ![vvbalaji](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/vvbalaji/32/3091_2.png) [@vvbalaji](https://discuss.dgraph.io/u/vvbalaji)\ **Post date:** [August 11, 2020, 3:35pm UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/5 "2020-08-11T15:35:16Z")
> [@pawan](#): > > GraphQL docs and its different sections should stand out. It should not just be another section along with Mutations, Query language and GraphQL± as that would confuse the users. What is the doc layout to achieve this? > [@pawan](#): > > Figure out which directory to keep the docs in, they can lie in a new folder inside the Dgraph repo for now and can be moved to a different repo if required later. @dmai: it will be in dgraph repo for now ---
**Author:** ![zhenni](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/zhenni/32/2817_2.png) [@zhenni](https://discuss.dgraph.io/u/zhenni)\ **Post date:** [August 11, 2020, 5:10pm UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/6 "2020-08-11T17:10:04Z")
@pawan I will have a meeting w/ our SEO agency today and will get a checklist for the merging. ---
**Author:** ![zhenni](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/zhenni/32/2817_2.png) [@zhenni](https://discuss.dgraph.io/u/zhenni)\ **Post date:** [August 12, 2020, 3:47am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/7 "2020-08-12T03:47:12Z")
@pawan @vvbalaji here is the note from the SEO agency on merging the GraphQL docs to under Dgraph. - Please ensure that 301 redirects are implemented (don’t use javascript redirects or meta refresh) - Don’t create redirect chains (where one redirect leads to another redirect, which leads to another redirect, ect). If possible, please link to the final destination URL - Ensure that any applicable navigation links are switched from [graphqp.dgraph.io](http://graphqp.dgraph.io) to [dgraph.io/docs/graphql](http://dgraph.io/docs/graphql) - Be sure to include the RankScience JS snippet on the new /docs/graphql subdirectory | ```auto ``` ---
**Author:** ![vvbalaji](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/vvbalaji/32/3091_2.png) [@vvbalaji](https://discuss.dgraph.io/u/vvbalaji)\ **Post date:** [August 12, 2020, 4:17am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/8 "2020-08-12T04:17:37Z")
Thanks @zhenni. How easy or difficult would it be for the SEO agency to verify that we did things the right way after the merge? ---
**Author:** ![zhenni](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/zhenni/32/2817_2.png) [@zhenni](https://discuss.dgraph.io/u/zhenni)\ **Post date:** [August 12, 2020, 4:57am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/9 "2020-08-12T04:57:08Z")
@vvbalaji they say they can check the merge the day after immediately and give us the feedback. So just let me know when the merge is done. 🙂 ---
**Author:** ![pawan](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/pawan/32/1946_2.png) [@pawan](https://discuss.dgraph.io/u/pawan)\ **Post date:** [August 12, 2020, 7:02am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/10 "2020-08-12T07:02:09Z")
Notes from meeting with @vardhanapoorv - Most of the docs have been ported atleast locally. Apoorv to fix broken internal links today and create a PR for the docs. - Apoorv to talk to @dmai about how to deploy this so that its available on [docs.dgraph.io/docs/graphql](http://docs.dgraph.io/docs/graphql) and get it up by tomorrow. - We start working on getting redirects in place tomorrow. Things to fix next week if we don’t find time this week: 1. Syntax highlighting for GraphQL - Modify Hugo theme to enable this. 2. Algolia search - GraphQL should have its own search and should not return results from Dgraph. 3. Edit Page button - Make this a variable within the theme so that it points to the correct place to edit GraphQL docs. 4. Tour link on top - Should be removed from GraphQL docs. ---
**Author:** ![pawan](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/pawan/32/1946_2.png) [@pawan](https://discuss.dgraph.io/u/pawan)\ **Post date:** [August 12, 2020, 7:03am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/11 "2020-08-12T07:03:11Z")
> [@vvbalaji](#): > > What is the doc layout to achieve this? The docs for GraphQL would lie in a different folder from the current Dgraph docs to achieve this. This is what Apoorv is currently doing. ---
**Author:** ![gja](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/gja/32/2654_2.png) [@gja](https://discuss.dgraph.io/u/gja)\ **Post date:** [August 12, 2020, 7:21am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/12 "2020-08-12T07:21:27Z")
Yes please, let’s move docs into a separate repo, primarily for practical reasons. - Don’t want to get approvals from dgraph CODE\_OWNERS for merging in Slash Docs - Don’t want to have to wait for CI, code checks for the docs ---
**Author:** ![mrjn](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/mrjn/32/775_2.png) [@mrjn](https://discuss.dgraph.io/u/mrjn)\ **Post date:** [August 12, 2020, 11:49am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/13 "2020-08-12T11:49:28Z")
@pawan get some help from @gja’s team to integrate Discourse comments to each page in the documentation. ---
**Author:** ![abhijit-kar](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/abhijit-kar/32/3726_2.png) [@abhijit-kar](https://discuss.dgraph.io/u/abhijit-kar)\ **Post date:** [August 12, 2020, 11:56am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/14 "2020-08-12T11:56:22Z")
This is awesome, each page will have it’s own FAQ section as well as answers! ---
**Author:** ![pawan](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/pawan/32/1946_2.png) [@pawan](https://discuss.dgraph.io/u/pawan)\ **Post date:** [August 12, 2020, 2:19pm UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/15 "2020-08-12T14:19:59Z")
> [@gja](#): > > Yes please, let’s move docs into a separate repo, primarily for practical reasons. Sounds good to me. We can move it do a different Git repo or maybe we can just rework the current repo to have Hugo docs instead of Gatsby docs. > [@mrjn](#): > > @pawan get some help from @gja’s team to integrate Discourse comments to each page in the documentation. Ok, let me talk to @gja about this tomorrow. An initial version of how these docs would look is live at [https://frosty-feynman-6ed421.netlify.app/how-dgraph-graphql-works/](https://frosty-feynman-6ed421.netlify.app/how-dgraph-graphql-works/). We’ll soon get it live at [Get started with Dgraph](http://docs.dgraph.io/docs/graphql). ---
**Author:** ![vvbalaji](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/vvbalaji/32/3091_2.png) [@vvbalaji](https://discuss.dgraph.io/u/vvbalaji)\ **Post date:** [August 12, 2020, 10:21pm UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/16 "2020-08-12T22:21:50Z")
@vardhanapoorv: where would [https://graphql.dgraph.io/dgraph-graphql/quick-start](https://graphql.dgraph.io/dgraph-graphql/quick-start) exist in the new merged doc? I am assuming you would be dropping ‘Tutorials’, ‘Example Apps’ and ‘Tools and Deployments’ sections from [https://graphql.dgraph.io/dgraph-graphql/](https://graphql.dgraph.io/dgraph-graphql/) as they don’t have any content. ---
**Author:** ![vardhanapoorv](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/vardhanapoorv/32/2441_2.png) [@vardhanapoorv](https://discuss.dgraph.io/u/vardhanapoorv)\ **Post date:** [August 13, 2020, 1:27pm UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/17 "2020-08-13T13:27:21Z")
@vvbalaji I ported the quick-start content today. The todo tutorial was already ported. The remaining sections like “example apps” can be added whenever we have content ready for those. I have added the GraphQL, Slash section to the Dgraph docs and created DQL section for GraphQL±, according to the discussion with @pawan today. Updated - [https://frosty-feynman-6ed421.netlify.app/](https://frosty-feynman-6ed421.netlify.app/). ---
**Author:** ![vvbalaji](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/vvbalaji/32/3091_2.png) [@vvbalaji](https://discuss.dgraph.io/u/vvbalaji)\ **Post date:** [August 13, 2020, 5:37pm UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/18 "2020-08-13T17:37:41Z")
Thanks @vardhanapoorv. @pawan do we have a sync up scheduled with Marisa for the new docs home page? ---
**Author:** ![pawan](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/pawan/32/1946_2.png) [@pawan](https://discuss.dgraph.io/u/pawan)\ **Post date:** [August 14, 2020, 11:42am UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/19 "2020-08-14T11:42:30Z")
Updates - [https://dgraph.io/docs/master/](https://dgraph.io/docs/master/) have been updated to have docs for GraphQL and Slash GraphQL. DQL is its own section now. This didn’t break any existing links for DQL pages. Things to do The sidebar menu should be better so that when we click on a level 1 folder, it should not automatically expand level 2 folders. Search has to be fixed to index the new pages. Deploy to release 20.07.0 as well. Redirection links have to be managed. Tour should be removed from the top menu as it is a tour of DQL only. @vvbalaji @mrjn please have a look to give any final feedback after which we’ll redirect [graphql.dgraph.io](http://graphql.dgraph.io) links to the docs. ---
**Author:** ![vardhanapoorv](https://yyz1.discourse-cdn.com/flex007/user_avatar/discuss.dgraph.io/vardhanapoorv/32/2441_2.png) [@vardhanapoorv](https://discuss.dgraph.io/u/vardhanapoorv)\ **Post date:** [August 17, 2020, 1:00pm UTC](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282/20 "2020-08-17T13:00:31Z")
The PR is raised for release v20.07. Need to add redirection from [graphql.dgraph.io](http://graphql.dgraph.io). List is prepared. cc @dmai Check why the search results on master are not updated. Regarding version v20.03 should a PR be raised for every v20.03.1, v20.03.2 etc or just the main one. [Next page](https://discuss.dgraph.io/t/merging-graphql-and-dgraph-docs/9282.md?page=2)