Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add templates to doc pages and give docs home one #1268

Merged
merged 18 commits into from
May 22, 2020
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions content/docs/index.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
template: 'doc-home'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it looks like we made cards general enough, do we need a separate template now?

Copy link
Contributor Author

@rogermparent rogermparent May 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, I expected to need to do something in another component but everything went fine with the new custom components in the body.
I'll remove this template frontmatter and the existing home template. We may need a unique template in the future, but we'll add it when that time comes.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hey, any update to this? are we removing the template?

Copy link
Contributor Author

@rogermparent rogermparent May 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I totally can, and quite quickly, but considering we don't know the exact direction this page is going I haven't committed a change to it yet.

Given my comment on the home issue, I think the best course of action is to temporarily go all-in on the home template and make it a standalone component. This allows us to not be limited in design and get the docs home we want up quickly.

My current plan is that once I get the design I'll make the template that's a React component implementing that design, and once that makes the Docs page match what we want, we merge to master- this first step of the plan lets us get a great docs home out before the important DVC 1.0 events around the corner because the implementation is already here and React components are the easiest to port to any other method down the line.

After we have a page we want made in a simple React component template, we can later quite easily port the page content to something more dev/editor friendly that lets editors change the page in MD.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rogermparent I would be happy if we can get something simple and clean like this - https://cube.dev/docs . I don't think we need something too complicated/custom at this point. Does it help to make a decision?

Also, we can take design ideas there (except icons of course :) ) . I'll ask designer after that to make us icons.

---

# DVC Documentation

Welcome! In here you may find all the guiding material and technical documents
Expand Down
10 changes: 7 additions & 3 deletions src/gatsby/models/docs/createPages.js
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
const path = require('path')
const GithubSlugger = require('github-slugger')

const slugger = new GithubSlugger()
Expand Down Expand Up @@ -43,6 +44,7 @@ const createPages = async ({ graphql, actions }) => {
id
rawMarkdownBody
slug
template
}
}
}
Expand All @@ -54,17 +56,19 @@ const createPages = async ({ graphql, actions }) => {
throw docsResponse.errors
}

const docComponent = require.resolve('../../../templates/doc-home.tsx')
const docComponent = require.resolve('../../../templates/doc.tsx')

docsResponse.data.docs.edges.forEach(doc => {
const {
node: { id, slug, rawMarkdownBody }
node: { id, slug, rawMarkdownBody, template }
} = doc
const headings = parseHeadings(rawMarkdownBody)

if (slug) {
actions.createPage({
component: docComponent,
component: template
? require.resolve(path.resolve('src', 'templates', template + '.tsx'))
: docComponent,
path: slug,
context: {
id,
Expand Down
3 changes: 2 additions & 1 deletion src/gatsby/models/docs/onCreateMarkdownContentNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ function createMarkdownDocsNode(api, { parentNode }) {
const fieldData = {
slug,
rawMarkdownBody: node.rawMarkdownBody,
sourcePath: relativePath
sourcePath: relativePath,
template: node.frontmatter.template
}

const docNode = {
Expand Down
3 changes: 2 additions & 1 deletion src/gatsby/models/markdown-content/fields.js
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,6 @@ module.exports = {
timeToRead: {
type: 'String!',
resolve: parentResolverPassthrough()
}
},
template: 'String'
}
7 changes: 2 additions & 5 deletions src/templates/doc-home.tsx
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
import React from 'react'
import { graphql } from 'gatsby'
import { Node } from 'unist'
import { getItemByPath } from '../utils/shared/sidebar'

import SEO from '../components/SEO'

Expand All @@ -27,11 +26,9 @@ const DocHomePage: React.FC<IDocHomePageProps> = ({
page: { htmlAst }
} = data

const { label } = getItemByPath(slug)

return (
<>
<SEO title={label} />
<SEO title="Home" />
<Documentation htmlAst={htmlAst} path={slug} headings={headings} />
</>
)
Expand All @@ -40,7 +37,7 @@ const DocHomePage: React.FC<IDocHomePageProps> = ({
export default DocHomePage

export const pageQuery = graphql`
query DocPage($id: String!) {
query DocHomePage($id: String!) {
page: docsPage(id: { eq: $id }) {
htmlAst
}
Expand Down
48 changes: 48 additions & 0 deletions src/templates/doc.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
import React from 'react'
import { graphql } from 'gatsby'
import { Node } from 'unist'
import { getItemByPath } from '../utils/shared/sidebar'

import SEO from '../components/SEO'

import Documentation from '../components/Documentation'

interface IDocPageProps {
data: {
page: {
htmlAst: Node
}
}
pageContext: {
slug: string
headings: []
}
}
shcheklein marked this conversation as resolved.
Show resolved Hide resolved

const DocPage: React.FC<IDocPageProps> = ({
data,
pageContext: { slug, headings }
}) => {
const {
page: { htmlAst }
} = data

const { label } = getItemByPath(slug)

return (
<>
<SEO title={label} />
<Documentation htmlAst={htmlAst} path={slug} headings={headings} />
</>
)
}

export default DocPage

export const pageQuery = graphql`
query DocPage($id: String!) {
page: docsPage(id: { eq: $id }) {
htmlAst
}
}
`