Merge branch 'master' into feature/some-more-docs

.editorconfig

@@ -8,5 +8,5 @@ indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.json]
+[*.{json,yml,yaml}]
 indent_size = 2

content/concepts/architecture.md

@@ -0,0 +1,6 @@
+---
+title: Architecture
+description: The architecture of Ocean Protocol with all its components and how they work together.
+---
+
+![Ocean Protocol Components](images/components.png 'Ocean Protocol Components')

content/concepts/ecosystem.md

@@ -0,0 +1,14 @@
+---
+title: Ecosystem
+description: The Ocean Protocol network consists of various components.
+---
+
+[Architecture](./architecture/)
+
+Learn about all of them here.
+
+-   💧 keeper. See also [Set Up a Keeper](/setup/keeper/)
+-   🐋 aquarius
+-   brizo
+-   🦄 pleuston
+-   🦑 squid

content/concepts/introduction.md

@@ -1,5 +1,6 @@
 ---
 title: Introduction
+description: Get up to speed with Ocean Protocol
 ---
 
 ## What is Ocean Protocol?

content/concepts/security.md

@@ -0,0 +1,3 @@
+---
+title: Security
+---

content/concepts/terminology.md

@@ -1,9 +1,8 @@
 ---
 title: Terminology
+description: Terminology specific to Ocean Protocol.
 ---
 
-There is terminology specific to Ocean Protocol.
-
 ## Asset
 
 A data set or data service.

content/concepts/vulnerabilities.md

@@ -0,0 +1,3 @@
+---
+title: Reporting vulnerabilities
+---

data/sections.yml

@@ -0,0 +1,11 @@
+- title: Core Concepts
+  description: Understand the fundamentals of Ocean Protocol.
+  link: /concepts/introduction/
+
+- title: Setup Guides
+  description: Setting up the Ocean Protocol components.
+  link: /setup/keeper/
+
+- title: Tutorials
+  description: Browse tutorials for most common setup and development use-cases.
+  link: /tutorials/jupyter/

data/sidebars/concepts.yml

@@ -0,0 +1,20 @@
+- group: Getting Started
+  items:
+    - title: What is Ocean Protocol?
+      link: /concepts/introduction/
+    - title: Ecosystem overview
+      link: /concepts/ecosystem/
+    - title: Terminology
+      link: /concepts/terminology/
+
+- group: Architecture
+  items:
+    - title: Overview
+      link: /concepts/architecture/
+
+- group: Security
+  items:
+    - title: Overview
+      link: /concepts/security/
+    - title: Reporting vulnerabilities
+      link: /concepts/vulnerabilities/

data/sidebars/setup.yml

@@ -0,0 +1,8 @@
+- group: Setup Guides
+  items:
+    - title: Set Up a Keeper
+      link: /setup/keeper/
+    - title: Set Up a Marketplace
+      link: /setup/marketplace/
+    - title: Publish Data or Services
+      link: /setup/publisher/

data/sidebars/tutorials.yml

@@ -0,0 +1,4 @@
+- group: Tutorials
+  items:
+    - title: Jupyter Notebooks
+      link: /tutorials/jupyter/

gatsby-config.js

@@ -19,6 +19,13 @@ module.exports = {
                 path: `${__dirname}/content`
             }
         },
+        {
+            resolve: 'gatsby-source-filesystem',
+            options: {
+                name: 'data',
+                path: `${__dirname}/data`
+            }
+        },
         {
             resolve: 'gatsby-transformer-remark',
             options: {
@@ -26,14 +33,21 @@ module.exports = {
                     {
                         resolve: 'gatsby-remark-images',
                         options: {
-                            maxWidth: 600
+                            maxWidth: 756,
+                            quality: 80,
+                            withWebp: true,
+                            linkImagesToOriginal: false,
+                            showCaptions: true
                         }
                     },
+                    'gatsby-remark-smartypants',
                     'gatsby-remark-prismjs',
-                    'gatsby-remark-autolink-headers'
+                    'gatsby-remark-autolink-headers',
+                    'gatsby-remark-relative-linker'
                 ]
             }
         },
+        'gatsby-transformer-yaml',
         {
             resolve: 'gatsby-plugin-sass',
             options: {

gatsby-node.js

@@ -4,10 +4,10 @@ const { createFilePath } = require('gatsby-source-filesystem')
 exports.onCreateNode = ({ node, getNode, actions }) => {
     const { createNodeField } = actions
 
-    if (node.internal.type === `MarkdownRemark`) {
+    if (node.internal.type === 'MarkdownRemark') {
         const fileNode = getNode(node.parent)
         const parsedFilePath = path.parse(fileNode.relativePath)
-        const slug = createFilePath({ node, getNode })
+        const slug = createFilePath({ node, getNode, basePath: 'content' })
         const section = parsedFilePath.dir
 
         createNodeField({

package.json

@@ -17,9 +17,11 @@
     "gatsby-remark-autolink-headers": "^2.0.10",
     "gatsby-remark-images": "^2.0.6",
     "gatsby-remark-prismjs": "^3.0.3",
+    "gatsby-remark-smartypants": "^2.0.6",
     "gatsby-source-filesystem": "^2.0.7",
     "gatsby-transformer-remark": "^2.1.11",
     "gatsby-transformer-sharp": "^2.1.8",
+    "gatsby-transformer-yaml": "^2.1.4",
     "intersection-observer": "^0.5.1",
     "node-sass": "^4.10.0",
     "prismjs": "^1.15.0",

plugins/gatsby-remark-relative-linker/index.js

@@ -0,0 +1,33 @@
+//
+// https://stackoverflow.com/a/48864225/733677
+//
+
+// const visit = require('unist-util-visit')
+
+// module.exports = ({ markdownAST }) => {
+//     visit(markdownAST, 'link', node => {
+//         if (node.url && node.url.endsWith('.md') && node.url.startsWith('./')) {
+//             node.url = node.url.replace(
+//                 /(.*)\.(\w{2}).md(#.*)?$/gi,
+//                 (match, base, hash) => {
+//                     return `/`
+//                 }
+//             )
+//         }
+
+//         if (
+//             node.url &&
+//             node.url.endsWith('.md') &&
+//             node.url.startsWith('../')
+//         ) {
+//             node.url = node.url.replace(
+//                 /(.*)\.(\w{2}).md(#.*)?$/gi,
+//                 (match, base, hash) => {
+//                     return `/`
+//                 }
+//             )
+//         }
+//     })
+
+//     return markdownAST
+// }

plugins/gatsby-remark-relative-linker/package.json

@@ -0,0 +1 @@
+{}

src/components/Content.jsx

@@ -0,0 +1,13 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import styles from './Content.module.scss'
+
+const Content = ({ children }) => (
+    <div className={styles.content}>{children}</div>
+)
+
+Content.propTypes = {
+    children: PropTypes.any.isRequired
+}
+
+export default Content

src/components/Content.module.scss

@@ -1,7 +1,7 @@
 @import 'variables';
 
-.main {
+.content {
     padding: 0 $spacer;
-    max-width: 45rem;
+    max-width: $break-point--large;
     margin: auto;
 }

src/components/Header.module.scss

@@ -3,17 +3,18 @@
 .header {
     background: $brand-black;
     width: 100%;
-    padding: $spacer / 2;
+    padding: $spacer / 2 0;
     padding-right: $spacer / 1.5;
 }
 
 .headerContent {
-    max-width: $break-point--huge;
+    max-width: $break-point--large;
     margin-left: auto;
     margin-right: auto;
     display: flex;
     justify-content: space-between;
     align-items: center;
+    padding: 0 $spacer;
 }
 
 .headerLogo {

src/components/HeaderSection.jsx

@@ -0,0 +1,18 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import Content from './Content'
+import styles from './HeaderSection.module.scss'
+
+const HeaderSection = ({ title }) => (
+    <header className={styles.headerSection}>
+        <Content>
+            <h1 className={styles.headerSectionTitle}>{title}</h1>
+        </Content>
+    </header>
+)
+
+HeaderSection.propTypes = {
+    title: PropTypes.string
+}
+
+export default HeaderSection

src/components/HeaderSection.module.scss

@@ -0,0 +1,12 @@
+@import 'variables';
+
+.headerSection {
+    padding: $spacer / 2 0;
+    border-bottom: .1rem solid $brand-grey-lighter;
+}
+
+.headerSectionTitle {
+    margin: 0;
+    font-size: $font-size-large;
+    color: $brand-grey-light;
+}

src/components/Layout.jsx

@@ -4,7 +4,6 @@ import Helmet from 'react-helmet'
 import { StaticQuery, graphql } from 'gatsby'
 
 import Header from './Header'
-import styles from './Layout.module.scss'
 
 const Layout = ({ children }) => (
     <StaticQuery
@@ -29,7 +28,7 @@ const Layout = ({ children }) => (
                     <html lang="en" />
                 </Helmet>
                 <Header siteTitle={data.site.siteMetadata.title} />
-                <main className={styles.main}>{children}</main>
+                <section>{children}</section>
             </>
         )}
     />

src/components/Sidebar.jsx

@@ -0,0 +1,101 @@
+import React, { Component } from 'react'
+import PropTypes from 'prop-types'
+import { Link } from 'gatsby'
+import styles from './Sidebar.module.scss'
+
+const SidebarLink = ({ link, title, linkClasses }) => {
+    if (link) {
+        if (link.match(/^\s?http(s?)/gi)) {
+            return (
+                <a href={link} target="_blank" rel="noopener noreferrer">
+                    {title}
+                </a>
+            )
+        } else {
+            return (
+                <Link to={link} className={linkClasses}>
+                    {title}
+                </Link>
+            )
+        }
+    } else {
+        return title
+    }
+}
+
+const SidebarList = ({ items, location }) => (
+    <ul className={styles.list}>
+        {items.map((item, j) => (
+            <li key={j}>
+                <SidebarLink
+                    link={item.link}
+                    title={item.title}
+                    linkClasses={
+                        item.link === location.pathname
+                            ? styles.active
+                            : styles.link
+                    }
+                />
+            </li>
+        ))}
+    </ul>
+)
+
+export default class Sidebar extends Component {
+    static propTypes = {
+        sidebar: PropTypes.string,
+        location: PropTypes.object.isRequired
+    }
+
+    static defaultProps = {
+        location: { pathname: `/` }
+    }
+
+    render() {
+        const { sidebar, location } = this.props
+
+        const sidebarfile = sidebar
+            ? require(`../../data/sidebars/${sidebar}.yml`) // eslint-disable-line
+            : []
+
+        if (!sidebarfile) {
+            return null
+        }
+
+        return (
+            <nav className={styles.sidebar}>
+                {sidebarfile.map((group, i) => (
+                    <div key={i}>
+                        <h4 className={styles.groupTitle}>
+                            {group.items[0].link ? (
+                                <SidebarLink
+                                    link={group.items[0].link}
+                                    title={group.group}
+                                    linkClasses={styles.groupTitleLink}
+                                />
+                            ) : (
+                                group.group
+                            )}
+                        </h4>
+                        <SidebarList
+                            key={i}
+                            items={group.items}
+                            location={location}
+                        />
+                    </div>
+                ))}
+            </nav>
+        )
+    }
+}
+
+SidebarLink.propTypes = {
+    link: PropTypes.string.isRequired,
+    title: PropTypes.string.isRequired,
+    linkClasses: PropTypes.string
+}
+
+SidebarList.propTypes = {
+    items: PropTypes.array.isRequired,
+    location: PropTypes.object.isRequired
+}

src/components/Sidebar.module.scss

@@ -0,0 +1,55 @@
+@import 'variables';
+
+.sidebar {
+    padding-top: $spacer / 2;
+}
+
+.groupTitle {
+    font-size: $font-size-small;
+    font-family: $font-family-button;
+    text-transform: uppercase;
+    margin-top: $spacer;
+    margin-bottom: $spacer / 4;
+}
+
+.groupTitleLink {
+    color: $brand-grey-light;
+
+    &:hover,
+    &:focus {
+        transform: none;
+        color: $brand-grey-light;
+    }
+}
+
+.list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    border-left: 1px solid $brand-grey-lighter;
+    margin-left: $spacer / 2;
+
+    li {
+        display: block;
+    }
+}
+
+.link {
+    color: $brand-grey;
+    display: inline-block;
+    padding: $spacer / 6 $spacer / 2;
+    border-left: .1rem solid transparent;
+    margin-left: -.05rem;
+
+    &:hover,
+    &:focus {
+        transform: none;
+        color: $brand-purple;
+    }
+}
+
+.active {
+    composes: link;
+    color: $brand-purple;
+    border-left-color: $brand-purple;
+}

src/pages/index.js

@@ -2,11 +2,13 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import { Link, graphql } from 'gatsby'
 import Layout from '../components/Layout'
+import Content from '../components/Content'
+import styles from './index.module.scss'
 
 const SectionLink = ({ to, title, children }) => (
     <Link to={to}>
-        <h3>{title}</h3>
+        <h3 className={styles.sectionTitle}>{title}</h3>
-        <p>{children}</p>
+        <p className={styles.sectionText}>{children}</p>
     </Link>
 )
 
@@ -16,43 +18,21 @@ SectionLink.propTypes = {
     children: PropTypes.any
 }
 
-const IndexPage = ({ data, location }) => {
+const IndexPage = ({ data, location }) => (
-    const { edges } = data.allMarkdownRemark
+    <Layout location={location}>
-
+        <Content>
-    const DocsList = edges.map(({ node }) => {
+            <ul className={styles.sections}>
-        const { title } = node.frontmatter
+                {data.allSectionsYaml.edges.map(({ node }) => (
-        const { slug } = node.fields
+                    <li key={node.title} className={styles.section}>
-
+                        <SectionLink to={node.link} title={node.title}>
-        return (
+                            {node.description}
-            <li key={node.id}>
+                        </SectionLink>
-                <Link to={slug}>{title}</Link>
+                    </li>
-            </li>
+                ))}
-        )
+            </ul>
-    })
+        </Content>
-
+    </Layout>
-    return (
+)
-        <Layout location={location}>
-            <h1>Hi there</h1>
-
-            <SectionLink to="/concepts/introduction/" title="Core Concepts">
-                Understand the fundamentals of Ocean Protocol.
-            </SectionLink>
-
-            <SectionLink to="/setup/" title="Setup Guides">
-                Setting up the Ocean Protocol components.
-            </SectionLink>
-
-            <SectionLink to="/tutorials/" title="Tutorials">
-                Browse tutorials for most common setup and development
-                use-cases.
-            </SectionLink>
-
-            <h1>Docs list</h1>
-
-            <ul>{DocsList}</ul>
-        </Layout>
-    )
-}
 
 IndexPage.propTypes = {
     data: PropTypes.object.isRequired,
@@ -61,20 +41,14 @@ IndexPage.propTypes = {
 
 export default IndexPage
 
-export const indexQuery = graphql`
+export const IndexQuery = graphql`
     query {
-        allMarkdownRemark {
+        allSectionsYaml {
             edges {
                 node {
-                    id
+                    title
-                    html
+                    description
-                    excerpt(pruneLength: 250)
+                    link
-                    frontmatter {
-                        title
-                    }
-                    fields {
-                        slug
-                    }
                 }
             }
         }

src/pages/index.module.scss

@@ -0,0 +1,39 @@
+@import 'variables';
+
+.sections {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    margin-top: $spacer * 2;
+
+    @media (min-width: $break-point--medium) {
+        display: flex;
+        justify-content: space-between;
+    }
+}
+
+.section {
+    margin-bottom: $spacer;
+
+    @media (min-width: $break-point--medium) {
+        flex: 0 0 30%;
+        margin-bottom: 0;
+    }
+
+    a {
+        display: block;
+        padding: $spacer * $line-height;
+        border-radius: $border-radius;
+        box-shadow: rgba($brand-black, .1) 0px 9px 18px;
+        color: $brand-grey;
+        height: 100%;
+    }
+}
+
+.sectionTitle {
+    margin-top: 0;
+}
+
+.sectionText {
+    margin-bottom: 0;
+}

src/pages/setup.js

@@ -0,0 +1,57 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Link, graphql } from 'gatsby'
+import Layout from '../components/Layout'
+import HeaderSection from '../components/HeaderSection'
+import Content from '../components/Content'
+
+const SetupIndexPage = ({ data, location }) => {
+    const { edges } = data.allMarkdownRemark
+
+    const SetupList = edges.map(({ node }) => {
+        const { title } = node.frontmatter
+        const { slug } = node.fields
+
+        return (
+            <li key={node.id}>
+                <Link to={slug}>{title}</Link>
+            </li>
+        )
+    })
+
+    return (
+        <Layout location={location}>
+            <HeaderSection title="Setup Guides" />
+            <Content>
+                <ul>{SetupList}</ul>
+            </Content>
+        </Layout>
+    )
+}
+
+export default SetupIndexPage
+
+SetupIndexPage.propTypes = {
+    data: PropTypes.object.isRequired,
+    location: PropTypes.object.isRequired
+}
+
+export const indexQuery = graphql`
+    query {
+        allMarkdownRemark(filter: { fields: { section: { eq: "setup" } } }) {
+            edges {
+                node {
+                    id
+                    html
+                    excerpt(pruneLength: 250)
+                    frontmatter {
+                        title
+                    }
+                    fields {
+                        slug
+                    }
+                }
+            }
+        }
+    }
+`

src/pages/tutorials.js

@@ -0,0 +1,59 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Link, graphql } from 'gatsby'
+import Layout from '../components/Layout'
+import HeaderSection from '../components/HeaderSection'
+import Content from '../components/Content'
+
+const TutorialsIndexPage = ({ data, location }) => {
+    const { edges } = data.allMarkdownRemark
+
+    const TutorialsList = edges.map(({ node }) => {
+        const { title } = node.frontmatter
+        const { slug } = node.fields
+
+        return (
+            <li key={node.id}>
+                <Link to={slug}>{title}</Link>
+            </li>
+        )
+    })
+
+    return (
+        <Layout location={location}>
+            <HeaderSection title="Tutorials" />
+            <Content>
+                <ul>{TutorialsList}</ul>
+            </Content>
+        </Layout>
+    )
+}
+
+export default TutorialsIndexPage
+
+TutorialsIndexPage.propTypes = {
+    data: PropTypes.object.isRequired,
+    location: PropTypes.object.isRequired
+}
+
+export const indexQuery = graphql`
+    query {
+        allMarkdownRemark(
+            filter: { fields: { section: { eq: "tutorials" } } }
+        ) {
+            edges {
+                node {
+                    id
+                    html
+                    excerpt(pruneLength: 250)
+                    frontmatter {
+                        title
+                    }
+                    fields {
+                        slug
+                    }
+                }
+            }
+        }
+    }
+`

src/styles/_variables.scss

@@ -30,9 +30,9 @@ $font-size-mini:        .65rem;
 $font-size-text:        $font-size-base;
 $font-size-label:       $font-size-base;
 $font-size-title:       1.4rem;
-$font-size-h1:          3.4rem;
+$font-size-h1:          3rem;
-$font-size-h2:          2.7rem;
+$font-size-h2:          2rem;
-$font-size-h3:          2rem;
+$font-size-h3:          1.7rem;
 $font-size-h4:          1.5rem;
 $font-size-h5:          1.125rem;
 

src/templates/Doc.jsx

@@ -2,6 +2,10 @@ import React, { Component } from 'react'
 import PropTypes from 'prop-types'
 import { graphql } from 'gatsby'
 import Layout from '../components/Layout'
+import Content from '../components/Content'
+import HeaderSection from '../components/HeaderSection'
+import Sidebar from '../components/Sidebar'
+import styles from './Doc.module.scss'
 
 export default class DocTemplate extends Component {
     static propTypes = {
@@ -10,12 +14,35 @@ export default class DocTemplate extends Component {
     }
 
     render() {
+        const { location } = this.props
         const post = this.props.data.markdownRemark
+        const { section } = post.fields
+        const { title, description } = post.frontmatter
 
         return (
-            <Layout location={this.props.location}>
+            <Layout location={location}>
-                <h1>{post.frontmatter.title}</h1>
+                <HeaderSection title={section} />
-                <div dangerouslySetInnerHTML={{ __html: post.html }} />
+                <Content>
+                    <main className={styles.wrapper}>
+                        <aside className={styles.sidebar}>
+                            <Sidebar location={location} sidebar={section} />
+                        </aside>
+
+                        <article className={styles.main}>
+                            <header className={styles.header}>
+                                <h1 className={styles.title}>{title}</h1>
+                                {description && (
+                                    <p className={styles.lead}>{description}</p>
+                                )}
+                            </header>
+
+                            <div
+                                className={styles.docContent}
+                                dangerouslySetInnerHTML={{ __html: post.html }}
+                            />
+                        </article>
+                    </main>
+                </Content>
             </Layout>
         )
     }
@@ -34,6 +61,10 @@ export const pageQuery = graphql`
             html
             frontmatter {
                 title
+                description
+            }
+            fields {
+                section
             }
         }
     }

src/templates/Doc.module.scss

@@ -0,0 +1,40 @@
+@import 'variables';
+
+.wrapper {
+    @media (min-width: $break-point--medium) {
+        display: flex;
+        justify-content: space-between;
+    }
+}
+
+.sidebar {
+    flex: 0 0 25%;
+}
+
+.main {
+    flex: 0 0 70%;
+}
+
+.header {
+    margin-top: $spacer;
+    margin-bottom: $spacer * $line-height;
+}
+
+.title {
+    font-size: $font-size-h1;
+    margin-top: 0;
+    margin-bottom: $spacer / $line-height;
+}
+
+.lead {
+    font-size: $font-size-large;
+}
+
+.docContent {
+    figcaption {
+        font-size: $font-size-small;
+        text-align: center;
+        color: $brand-grey-light;
+        margin-top: $spacer / 2;
+    }
+}