From c4f51335314eadcad02840e04c69c3232c5c3421 Mon Sep 17 00:00:00 2001 From: Aaron Carlino Date: Fri, 13 Dec 2019 10:52:39 +1300 Subject: [PATCH] Initial commit of userdocs merge --- README.md | 30 ++- gatsby-browser.js | 1 - gatsby-config.js | 26 +- gatsby-node.js | 43 ++- gatsby-ssr.js | 7 +- package.json | 6 +- sources-docs.js | 20 ++ sources-user.js | 447 ++++++++++++++++++++++++++++++++ src/components/DocsPage.tsx | 35 +++ src/components/Header.tsx | 6 +- src/components/Layout.tsx | 6 +- src/components/Nav.tsx | 19 +- src/components/NodeProvider.tsx | 9 +- src/components/SEO.tsx | 6 +- src/components/SearchBox.tsx | 5 +- src/hooks/useHierarchy.ts | 1 - src/templates/docs-template.tsx | 39 +-- src/types/index.ts | 1 + src/utils/nodes.ts | 27 +- src/utils/rewriteLink.ts | 25 +- src/utils/sortFiles.ts | 2 +- userhelp-imports.js | 338 ------------------------ 22 files changed, 658 insertions(+), 441 deletions(-) create mode 100644 sources-docs.js create mode 100644 sources-user.js create mode 100644 src/components/DocsPage.tsx delete mode 100644 userhelp-imports.js diff --git a/README.md b/README.md index fb78edb..0b643d0 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,9 @@ # doc.silverstripe.org -This repository contains the source code powering [SilverStripe's -developer documentation website](https://docs.silverstripe.org). +This repository contains the source code powering [the Silverstripe CMS +developer documentation website](https://docs.silverstripe.org) and +[userhelp website](https://userhelp.silverstripe.org). This application is build on [Gatsby](https://gatsbyjs.com), a static site generator based on [React](https://reactjs.org). It sources content @@ -61,6 +62,20 @@ gatsby serve These commands will give you an exact representation of how the site will run on a production server, with statically generated html files and server-side rendering. +## Toggling between docs and userhelp + +Whether the application uses the `docs.silverstripe.org` content or `userhelp.silverstripe.org` is determined +by the environment variable, `DOCS_CONTEXT`. You can set this in the `.env.development` file, or use one of +the script shortcuts: + +``` +yarn dev-docs +yarn dev-user +yarn build-docs +yarn build-user +``` + + ## Developing From within `path/to/ssdocs`, run the command @@ -85,7 +100,7 @@ your content changes, since the remote repositories are the source of truth. ## Deploying content changes Once your contribution has been merged into the master branch, it will be deployed to production via a -Github action in the `silverstripe-framework` repository. +Github action in the repository that holds the markdown files (e.g. `silverstripe/silverstripe-framework` for docs). ## Deploying app changes @@ -93,11 +108,12 @@ Once your change is merged in to the `master` branch of this repository, it will ## Contribution -To contribute an improvement to the https://docs.silverstripe.org functionality or +To contribute an improvement to the https://docs.silverstripe.org or https://userhelp.silverstripe.org functionality or theme, submit a pull request on the [GitHub project](https://github.com/silverstripe/doc.silverstripe.org). Any approved pull requests will make -their way onto the https://docs.silverstripe.org site in the next release. +their way onto the https://docs.silverstripe.org or https://userhelp.silverstripe.org sites in the next release. If you wish to edit the documentation content, submit a pull request on the -[framework Github project](https://github.com/silverstripe/silverstripe-framework). Updated -documentation content is uploaded daily to [doc.silverstripe.org](https://docs.silverstripe.org) via a build hook. \ No newline at end of file +[framework Github project](https://github.com/silverstripe/silverstripe-framework) or the +[userhelp documentation](https://github.com/silverstripe/silverstripe-userhelp-content) repository +or corresponding module. \ No newline at end of file diff --git a/gatsby-browser.js b/gatsby-browser.js index d407612..783953e 100644 --- a/gatsby-browser.js +++ b/gatsby-browser.js @@ -5,7 +5,6 @@ require('./src/theme/assets/search/algolia.css'); const React = require('react'); const Layout = require('./src/components/Layout').default; const NodeProvider = require('./src/components/NodeProvider').default; -const { setCurrentPath } = require('./src/utils/nodes'); const smoothScroll = require('smooth-scroll'); if (typeof window !== "undefined") { diff --git a/gatsby-config.js b/gatsby-config.js index 6513983..dc3288f 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -1,5 +1,7 @@ const path = require('path'); -const userhelpImports = require('./userhelp-imports'); +const sources = process.env.DOCS_CONTEXT === 'user' + ? require('./sources-user') + : require('./sources-docs'); module.exports = { siteMetadata: { @@ -14,6 +16,7 @@ module.exports = { `gatsby-plugin-sass`, `gatsby-plugin-sharp`, `gatsby-plugin-sitemap`, +<<<<<<< HEAD `gatsby-plugin-netlify`, { resolve: `gatsby-source-git`, @@ -61,13 +64,18 @@ module.exports = { }, // ...userhelpImports >>>>>>> Docs/userguide switching +======= + + ...sources.slice(0, 4), +>>>>>>> Initial commit of userdocs merge { resolve: `gatsby-source-filesystem`, options: { name: `watcher`, - path: `${__dirname}/.cache/gatsby-source-git/` + // In dev mode, watch all the source files. Otherwise, point it at a meaningless directory + path: `${__dirname}/.cache/gatsby-source-git/`, } - }, + }, { resolve: 'gatsby-transformer-remark', options: { @@ -82,12 +90,22 @@ module.exports = { } } }, - `gatsby-remark-copy-linked-files`, { resolve: `gatsby-remark-images`, options: { maxWidth: 850, + linkImagesToOriginal: false, }, +<<<<<<< HEAD +======= + }, + { + resolve: `gatsby-remark-copy-linked-files`, + options: { + // Links to markdown files should be considered links to pages, not downloads. + ignoreFileExtensions: [`md`], + } +>>>>>>> Initial commit of userdocs merge }, ] } diff --git a/gatsby-node.js b/gatsby-node.js index 7f50950..e2c43ef 100644 --- a/gatsby-node.js +++ b/gatsby-node.js @@ -3,15 +3,13 @@ const fs = require('fs'); const { createFilePath } = require(`gatsby-source-filesystem`); const fileToTitle = require('./src/utils/fileToTitle'); -const createSlug = ({path, version, category, thirdparty}) => { - const [_, lang, ...rest] = path.split('/'); +const createSlug = ({path, version, thirdparty}) => { + const rest = path.split('/'); const parts = [ - lang, + 'en', version, - // use suburl "userhelp" for all user docs - category === 'user' && 'userhelp', - // thirdparty modules are under /optional_features/ (coupling) - thirdparty && `optional_features/${thirdparty}`, + // thirdparty modules are explicitly pathed + thirdparty, ...rest, ].filter(p => p); @@ -33,7 +31,7 @@ exports.onCreateNode = async ({ node, getNode, getNodesByType, actions, createNo const fileNode = getNode(node.parent); const [category, version, thirdparty] = parseName(fileNode.sourceInstanceName); - // The gatsby-source-filesystem plugins are registered to collect from the same path + // The gatsby-sgatsbource-filesystem plugins are registered to collect from the same path // that the git source writes to, so we get the watch task (hot reload on content changes) // But we don't want duplicate document pages for each source plugin, so // we bail out if we already have the file. However, we need to ensure @@ -47,14 +45,14 @@ exports.onCreateNode = async ({ node, getNode, getNodesByType, actions, createNo // Pair the document with its watched file so we can inject it into the template // as a dependency. existing.watchFile___NODE = node.id; - return; } + return; } - + const basePath = category === 'user' ? `docs/en/userguide` : `docs/en`; const filePath = createFilePath({ node, getNode, - basePath: `docs` + basePath, }); let fileTitle = path.basename(node.fileAbsolutePath, '.md'); const isIndex = fileTitle === 'index'; @@ -65,12 +63,21 @@ exports.onCreateNode = async ({ node, getNode, getNodesByType, actions, createNo const slug = createSlug({ path: filePath, version, - category, thirdparty, }); + const parentSlug = `${path.resolve(slug, '../')}/`; const unhideSelf = false; + // Most of these don't exist in userhelp, so force them into the schema by un-nulling them. + const frontmatter = { + introduction: ``, + icon: `file-alt`, + iconBrand: ``, + hideChildren: false, + ...node.frontmatter, + }; + const docData = { isIndex, filePath, @@ -79,7 +86,11 @@ exports.onCreateNode = async ({ node, getNode, getNodesByType, actions, createNo parentSlug, unhideSelf, category, +<<<<<<< HEAD ...node.frontmatter, +======= + ...frontmatter, +>>>>>>> Initial commit of userdocs merge }; if (!docData.title || docData.title === '') { @@ -104,10 +115,16 @@ exports.onCreateNode = async ({ node, getNode, getNodesByType, actions, createNo }; +<<<<<<< HEAD exports.createPages = async ({ actions, graphql, getNodesByType }) => { const { createPage, createRedirect } = actions; const docTemplate = path.resolve(`src/templates/docs-template.tsx`); +======= +exports.createPages = async ({ actions, graphql }) => { + const { createPage } = actions; + const docsTemplate = path.resolve(`src/templates/docs-template.tsx`) +>>>>>>> Initial commit of userdocs merge const result = await graphql(` { allSilverstripeDocument { @@ -126,7 +143,7 @@ exports.createPages = async ({ actions, graphql, getNodesByType }) => { .forEach(node => { createPage({ path: node.slug, - component: docTemplate, + component: docsTemplate, context: { id: node.id, slug: node.slug, diff --git a/gatsby-ssr.js b/gatsby-ssr.js index 3640327..4be54e1 100644 --- a/gatsby-ssr.js +++ b/gatsby-ssr.js @@ -1,7 +1,6 @@ const React = require('react'); const Layout = require('./src/components/Layout').default; const NodeProvider = require('./src/components/NodeProvider').default; -const { setCurrentPath } = require('./src/utils/nodes'); /** * Applies the node provider (static query of all documents) @@ -9,7 +8,7 @@ const { setCurrentPath } = require('./src/utils/nodes'); */ exports.wrapPageElement = ({ element, props }) => { return ( - + {element} @@ -17,9 +16,7 @@ exports.wrapPageElement = ({ element, props }) => { ); }; - -exports.onRenderBody = ({ pathname, setPostBodyComponents, setHeadComponents }) => { - setCurrentPath(pathname); +exports.onRenderBody = ({ setPostBodyComponents, setHeadComponents }) => { // Rules that cannot be touched by purgecss because they come in from client side rendering setHeadComponents([