Add cards to the home page (#1268)

* Add templates to doc pages and give docs home one

- Default docs page template moved from `src/templates/doc-home.tsx` to
  `src/templates/doc.tsx`. A new homepage-specific (but currently identical)
  template has been added in its place.

- Added frontmatter to docs home source to define the template

- Docs now have a "template" field, which when defined changes the component
  used to make its page. This is a file relative to `src/templates` with the
  extension left off. This defaults to `doc`, or the file
  `src/templates/doc.tsx`. This is not currently on blog posts.

* Add "card" and "cards" custom components to Docs

* Create some example content with the new custom card components

This is not intended to be final, but show off the general premise of
how using custom components for this kind of layout would look like.

The card and cards components are, on top of being fully stylable with CSS
modules, capable of using arbitrary Markdown images or elements as the card
"logo" when the `logo` prop is set to `true` (or anything truthy, like the
string `"true"`). This works around the complexity of working in custom image
capability by leaning on the one we already have in Markdown.

To make a card with a logo, set the "logo" prop to true and make sure the first
element in the card contains the image you want- this element will be set aside
in its own div, with the rest of the contents displayed beside it using `flex`

There are some quirks with Remark custom components, though:

- custom components aren't indented

- custom components must be contained to one line, including props.

- custom components can include Markdown, but there must be an empty line
  between the transition.

- self-closing tags aren't supported

Should we use custom components more often, we can migrate to MDX (I actually
already have a fully working branch with it that I made on my own time) which
handles this syntax much more comfortably because it's designed around the
concept. All our custom remark-based logic will cleanly port because MDX
actually uses Remark in its pipeline.

* Resolve TS issues in example

* Remove doc home template and example images

In an effort to make the current solution good enough to fit release, I've
removed the alternate template since this branch currently favors custom
components.

* Add example images to all home cards, and remove example heading.

* Remove images from cards in doc home content

* Improve Cards and add href feature.

Cards now accept a `href` prop, which turns the whole card into a link. This is
our Link wrapper, so we get the same automatic `rel` and `target` setting for
external links as well as Gatsby Link for internal ones.

This link spans the whole card, and has some styling to go along with it.
Currently the hover style is set to a slight grow animation, but it could be
anything.

Most of the `children`-modifying hackery has been removed in favor of wrapping
all Cards. This also brings a degree of consistency to Cards, and we can apply
indivual styles if the need arises. It's still needed for the Card Images,
however, since newlines that show up in `children` are mandatory for how
rehype's React and MD are separated.

* Change doc home content

- Make each Card a single link applied via the new `href` part

- Add headings to each card

- Remove card icons

* Change hover animation to background-color

Now they match the right side buttons, aside from the animated transition.

* index: simplify and update content

* Restyled by prettier (#1335)

Co-authored-by: Restyled.io <[email protected]>

* home page, get started - fix the link

* docs index - change oder, cards should go first

* home index: return use cases

* card style: less contrast for the heading

* docs home page: update cards text

Co-authored-by: Ivan Shcheklein <[email protected]>
Co-authored-by: restyled-io[bot] <32688539+restyled-io[bot]@users.noreply.github.com>
Co-authored-by: Restyled.io <[email protected]>

content/docs/index.md

@@ -4,7 +4,33 @@ Welcome! In here you may find all the guiding material and technical documents
 needed to learn about DVC: how to use it, how it works, and where to go for
 additional resources.
 
-## Before you start
+<cards>
+
+<card href="/doc/tutorials/get-started" heading="Get Started">
+
+A step-by-step introduction into basic DVC features
+
+</card>
+
+<card href="/doc/user-guide" heading="User Guide">
+
+Study the detailed inner-workings of DVC in its user guide
+
+</card>
+
+<card href="/doc/use-cases" heading="Use Cases">
+
+Non-exhaustive list of scenarios DVC can help with
+
+</card>
+
+<card href="/doc/command-reference" heading="Command Reference">
+
+See all of DVC's commands
+
+</card>
+
+</cards>
 
 ✅ Please join our [community](/community) or use the [support](/support)
 channels if you have any questions or need specific help. We are very responsive
@@ -15,15 +41,3 @@ us a ⭐ if you like the project!
 
 ✅ Contribute to DVC [on GitHub](https://github.com/iterative/dvc) or help us
 improve this [documentation](https://github.com/iterative/dvc.org) 🙏.
-
-## Main topics
-
-- Learn how to [install](/doc/install) and
-  [get started](/doc/tutorials/get-started) with DVC in the first sections.
-- Explore the main [reasons](/doc/use-cases) to adopt DVC.
-- Study the detailed [inner-workings](/doc/user-guide) of DVC, as well as each
-  one of its [commands](/doc/command-reference) and Python
-  [functions](/doc/api-reference).
-
-Please choose a topic from the sidebar to the left, or click the `Next` button
-below to start from the beginning ↘

src/components/Documentation/Markdown/index.tsx

@@ -50,11 +50,66 @@ const Abbr: React.FC<{ children: [string] }> = ({ children }) => {
   return <Tooltip text={children[0]} />
 }
 
+const Cards: React.FC = ({ children }) => {
+  return <div className={styles.cards}>{children}</div>
+}
+
+const InnerCard: React.FC<{
+  href?: string
+  className?: string
+}> = ({ href, children, className }) =>
+  href ? (
+    <Link href={href} className={className}>
+      {children}
+    </Link>
+  ) : (
+    <div className={className}>{children}</div>
+  )
+
+const Card: React.FC<{
+  icon?: string
+  heading?: string
+  href?: string
+  headingtag:
+    | string
+    | React.FC<{
+        className: string
+      }>
+}> = ({ children, icon, heading, headingtag: Heading = 'h3', href }) => {
+  let iconElement
+
+  if (Array.isArray(children) && icon) {
+    const firstRealItemIndex = children.findIndex(x => x !== '\n')
+    iconElement = children[firstRealItemIndex]
+    children = children.slice(firstRealItemIndex + 1)
+  }
+
+  return (
+    <div className={styles.cardWrapper}>
+      <InnerCard href={href} className={styles.card}>
+        {iconElement && <div className={styles.cardIcon}>{iconElement}</div>}
+        <div className={styles.cardContent}>
+          {heading && (
+            <Heading className={styles.cardHeading}>{heading}</Heading>
+          )}
+          {children}
+        </div>
+      </InnerCard>
+    </div>
+  )
+}
+
 const renderAst = new rehypeReact({
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   createElement: React.createElement as any,
   Fragment: React.Fragment,
-  components: { details: Details, abbr: Abbr, a: Link }
+  components: {
+    details: Details,
+    abbr: Abbr,
+    a: Link,
+    card: Card,
+    cards: Cards
+  }
 }).Compiler
 
 interface IMarkdownProps {

src/components/Documentation/Markdown/styles.module.css

@@ -340,3 +340,81 @@
     margin-top: 2px;
   }
 }
+
+.cards {
+  display: flex;
+  flex-flow: column nowrap;
+  margin: 1rem 0;
+
+  & > div {
+    padding: 0.5rem 0.1rem;
+  }
+
+  @media screen and (min-width: 1024px) {
+    margin: 2rem -0.5rem;
+    flex-flow: row wrap;
+
+    .cardWrapper {
+      flex: 1 0 50%;
+      padding: 0.5rem;
+      min-height: 7rem;
+    }
+
+    .card {
+      height: 100%;
+    }
+  }
+}
+
+.card {
+  border: 1px solid gray;
+  border-radius: 10px;
+  padding: 0.75rem 1rem;
+  display: flex;
+  width: 100%;
+  height: 100%;
+  flex-flow: row nowrap;
+  align-items: center;
+  box-sizing: border-box;
+
+  p {
+    margin: 0;
+  }
+
+  .cardIcon {
+    box-sizing: border-box;
+    display: block;
+    padding: 0;
+    padding-right: 0.75rem;
+    flex: 0 0 75px;
+
+    * {
+      margin: 0;
+      padding: 0;
+      display: block;
+    }
+  }
+
+  .cardHeading {
+    margin: 0;
+    margin-bottom: 0.25em;
+    font-weight: bold;
+    color: var(--color-gray-dark);
+  }
+
+  .cardContent {
+    flex: 1;
+  }
+}
+
+a.card {
+  color: inherit;
+  text-decoration: inherit;
+  transition: background-color 0.3s ease-in-out;
+  background-color: #fff;
+
+  &:hover {
+    text-decoration: inherit;
+    background-color: var(--color-light-blue);
+  }
+}

src/gatsby/models/docs/createPages.js

@@ -1,3 +1,4 @@
+const path = require('path')
 const GithubSlugger = require('github-slugger')
 
 const slugger = new GithubSlugger()
@@ -43,6 +44,7 @@ const createPages = async ({ graphql, actions }) => {
               id
               rawMarkdownBody
               slug
+              template
             }
           }
         }
@@ -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,

src/gatsby/models/docs/createSchemaCustomization.js

@@ -10,7 +10,8 @@ async function createSchemaCustomization(api) {
       name: 'DocsPage',
       interfaces: ['Node'],
       fields: {
-        ...markdownParentFields
+        ...markdownParentFields,
+        template: 'String'
       }
     })
   ]

src/gatsby/models/docs/onCreateMarkdownContentNode.js

@@ -14,7 +14,8 @@ function createMarkdownDocsNode(api, { parentNode }) {
   const fieldData = {
     slug,
     rawMarkdownBody: node.rawMarkdownBody,
-    sourcePath: relativePath
+    sourcePath: relativePath,
+    template: node.frontmatter.template
   }
 
   const docNode = {

src/gatsby/models/markdown-content/fields.js

@@ -12,5 +12,6 @@ module.exports = {
   timeToRead: {
     type: 'String!',
     resolve: parentResolverPassthrough()
-  }
+  },
+  template: 'String'
 }

src/templates/doc-home.tsx → src/templates/doc.tsx

@@ -7,7 +7,7 @@ import SEO from '../components/SEO'
 
 import Documentation from '../components/Documentation'
 
-interface IDocHomePageProps {
+interface IDocPageProps {
   data: {
     page: {
       htmlAst: Node
@@ -19,7 +19,7 @@ interface IDocHomePageProps {
   }
 }
 
-const DocHomePage: React.FC<IDocHomePageProps> = ({
+const DocPage: React.FC<IDocPageProps> = ({
   data,
   pageContext: { slug, headings }
 }) => {
@@ -37,7 +37,7 @@ const DocHomePage: React.FC<IDocHomePageProps> = ({
   )
 }
 
-export default DocHomePage
+export default DocPage
 
 export const pageQuery = graphql`
   query DocPage($id: String!) {