From 181fef9e997bfd600574f4751e2dfffbefd9992d Mon Sep 17 00:00:00 2001 From: Aaron Carlino Date: Tue, 19 Nov 2019 16:29:29 +1300 Subject: [PATCH] New API links, regex debugging --- index.html | 42 ------------------------------ src/pages/index.tsx | 2 +- src/templates/docs-template.tsx | 1 - src/theme/assets/scss/ss-docs.scss | 6 ++++- src/utils/cleanApiTags.ts | 6 ++++- src/utils/cleanHeaders.ts | 4 +++ src/utils/nodes.ts | 38 +++++++++++++++++++++++++-- src/utils/parseChildrenOf.ts | 4 +++ src/utils/rewriteAPILink.ts | 5 +++- src/utils/rewriteHeader.ts | 4 +++ src/utils/rewriteLink.ts | 13 ++++++++- src/utils/rewriteTable.ts | 6 +++++ 12 files changed, 81 insertions(+), 50 deletions(-) delete mode 100644 index.html diff --git a/index.html b/index.html deleted file mode 100644 index 803c9f9..0000000 --- a/index.html +++ /dev/null @@ -1,42 +0,0 @@ -SilverStripe Documentation | SilverStripe Documentation

Getting Started with SilverStripe

-

Before you start developing your first web application, you'll need to install the latest version of SilverStripe onto -a web server. The Getting Started section will show you what -server requirements you will need to meet and how to -download and install SilverStripe.

-

To check out the features that SilverStripe offers without installing it, read the Feature Overview -and play with the interactive demo website.

-

Getting support

-

SilverStripe has an wide range of options for getting support:

- -

Building your first SilverStripe Web application

-

Once you have completed the Getting Started guide and have got SilverStripe -installed and running, the following Tutorials will lead through the basics and core concepts of -SilverStripe.

-

Make sure you know the basic concepts of PHP5 before attempting to follow the tutorials. If you have not programmed with PHP5 be sure to read the Introduction to PHP5 (zend.com).

-

SilverStripe Concepts

-

The Developer Guides contain more detailed documentation on certain SilverStripe topics, 'how to' -examples and reference documentation.

Contributing to SilverStripe

-

The SilverStripe Framework, Content Management System and related websites are open source and welcome community -contributions.

Edit on Github
\ No newline at end of file diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 9c71e62..23baedc 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -1,5 +1,5 @@ import React, { useEffect } from 'react' -import { Redirect, navigate } from '@reach/router' +import { navigate } from '@reach/router' const IndexPage = () => { useEffect(() => { diff --git a/src/templates/docs-template.tsx b/src/templates/docs-template.tsx index bfe101a..7429668 100644 --- a/src/templates/docs-template.tsx +++ b/src/templates/docs-template.tsx @@ -55,7 +55,6 @@ export const pageQuery = graphql` } } } - } } ` diff --git a/src/theme/assets/scss/ss-docs.scss b/src/theme/assets/scss/ss-docs.scss index c98bb89..f6604e1 100644 --- a/src/theme/assets/scss/ss-docs.scss +++ b/src/theme/assets/scss/ss-docs.scss @@ -215,4 +215,8 @@ h1, h2, h3 { } .gatsby-highlight { margin: 2rem 0; -} +} + +.api-link { + border-bottom: 1px dashed $gray-700; +} diff --git a/src/utils/cleanApiTags.ts b/src/utils/cleanApiTags.ts index e2f2820..4ba00b5 100644 --- a/src/utils/cleanApiTags.ts +++ b/src/utils/cleanApiTags.ts @@ -1,7 +1,11 @@ +/** + * Completes the shorthand [api:Something] syntax to [api:Something](Something) + * @param html + */ const cleanApiTags = (html: string): string => { return html.replace( /\[api:(.*?)\]([^(])/g, - (_, query, next) => `${query}${next}` + (_, query, next) => `${query}${next}` ) }; diff --git a/src/utils/cleanHeaders.ts b/src/utils/cleanHeaders.ts index 8fa0e55..6ce7d6f 100644 --- a/src/utils/cleanHeaders.ts +++ b/src/utils/cleanHeaders.ts @@ -1,3 +1,7 @@ +/** + * Removes the tags caused by underscores in the {#id_with_underscores} + * @param html + */ const cleanHeaders = (html: string): string => { return html.replace( /(.*?)(\{#.*?<\/?em>.*?})/g, diff --git a/src/utils/nodes.ts b/src/utils/nodes.ts index 12faba8..83d8208 100644 --- a/src/utils/nodes.ts +++ b/src/utils/nodes.ts @@ -13,6 +13,9 @@ const navChildrenMap = new Map(); const siblingMap = new Map(); const parentMap = new Map(); +/** + * Get all documents in the source + */ const getNodes = (): SilverstripeDocument[] => { if (__nodes) { return __nodes; @@ -44,6 +47,12 @@ const getNodes = (): SilverstripeDocument[] => { return __nodes; }; +/** + * Get the children of a given node + * + * @param node + * @param includeFolders + */ const getChildren = ( node: SilverstripeDocument, includeFolders: boolean = true @@ -64,6 +73,11 @@ const getChildren = ( return childrenMap.get(sku); } +/** + * Get children of a given node that should be shown in navigation + * + * @param node + */ const getNavChildren = (node: SilverstripeDocument): SilverstripeDocument[] => { if (navChildrenMap.has(node.slug)) { return navChildrenMap.get(node.slug); @@ -78,6 +92,11 @@ const getNavChildren = (node: SilverstripeDocument): SilverstripeDocument[] => { return navChildrenMap.get(node.slug); }; +/** + * Get the siblings of a given node + * + * @param node + */ const getSiblings = (node: SilverstripeDocument): SilverstripeDocument[] => { if (siblingMap.has(node.slug)) { return siblingMap.get(node.slug); @@ -90,6 +109,10 @@ const getSiblings = (node: SilverstripeDocument): SilverstripeDocument[] => { return siblingMap.get(node.slug); }; +/** + * Get the parent of a given node + * @param node + */ const getParent = (node: SilverstripeDocument): SilverstripeDocument | null => { if (parentMap.has(node.slug)) { return parentMap.get(node.slug); @@ -103,8 +126,14 @@ const getParent = (node: SilverstripeDocument): SilverstripeDocument | null => { return parentMap.get(node.slug); }; +/** + * Get the current node. Must be set by setCurrentNode(string: slug) + */ const getCurrentNode = (): SilverstripeDocument | null => __currentNode; +/** + * Get the home page + */ const getHomePage = (): SilverstripeDocument | null => { if (__home) { return __home; @@ -118,8 +147,15 @@ const getHomePage = (): SilverstripeDocument | null => { return __home; }; +/** + * Get the selected version + */ const getCurrentVersion = (): string => __currentVersion || '4'; +/** + * Set the current node by its slug. + * @param slug + */ const setCurrentNode = (slug: string): void => { const currentNode = getNodes().find(n => n.slug === slug) || null; __currentNode = currentNode; @@ -132,8 +168,6 @@ const setCurrentNode = (slug: string): void => { } }; - - export { getNodes, getChildren, diff --git a/src/utils/parseChildrenOf.ts b/src/utils/parseChildrenOf.ts index 1ba5a7d..bbb02e7 100644 --- a/src/utils/parseChildrenOf.ts +++ b/src/utils/parseChildrenOf.ts @@ -2,6 +2,10 @@ import { ReactElement, createElement } from 'react'; import ChildrenOf from '../components/ChildrenOf'; import { getCurrentNode } from '../utils/nodes'; +/** + * Turn [CHILDREN ... ] into a proper React component. + * @param data + */ const parseChildrenOf = (data: any): ReactElement|false => { const currentNode = getCurrentNode(); let matches; diff --git a/src/utils/rewriteAPILink.ts b/src/utils/rewriteAPILink.ts index af5933c..c9fe60c 100644 --- a/src/utils/rewriteAPILink.ts +++ b/src/utils/rewriteAPILink.ts @@ -1,4 +1,7 @@ - +/** + * If an href is preceded with api:, rewrite it to the api.silverstripe.org site + * @param link + */ const rewriteAPILink = (link: string): string => { const version = 4; const match = link.match(/api\:(.*)/); diff --git a/src/utils/rewriteHeader.ts b/src/utils/rewriteHeader.ts index 39a864b..5c143b4 100644 --- a/src/utils/rewriteHeader.ts +++ b/src/utils/rewriteHeader.ts @@ -1,6 +1,10 @@ import { createElement, ReactElement } from "react"; import { DomElement } from 'html-react-parser'; +/** + * If a header has a {#explicit-id}, add it as an attribute + * @param domNode + */ const rewriteHeaders = (domNode: DomElement): ReactElement | false => { if (!domNode.name) { return false; diff --git a/src/utils/rewriteLink.ts b/src/utils/rewriteLink.ts index 30bcb0b..f1fa272 100644 --- a/src/utils/rewriteLink.ts +++ b/src/utils/rewriteLink.ts @@ -10,6 +10,13 @@ interface LinkAttributes { }; +/** + * Ensure links use the Gatsby component. Client-side routing FTW + * + * @param attribs + * @param children + * @param parseOptions + */ const rewriteLink = ( attribs: LinkAttributes, children: DomElement[], @@ -28,7 +35,11 @@ const rewriteLink = ( const newHref = rewriteAPILink(href); return createElement( 'a', - { href: newHref, target: '_blank' }, + { + className: 'api-link', + href: newHref, + target: '_blank' + }, domToReact(children, parseOptions) ); } diff --git a/src/utils/rewriteTable.ts b/src/utils/rewriteTable.ts index c792a64..280c216 100644 --- a/src/utils/rewriteTable.ts +++ b/src/utils/rewriteTable.ts @@ -1,6 +1,12 @@ import { DomElement, HTMLReactParserOptions, domToReact } from "html-react-parser"; import { ReactElement, createElement } from "react"; +/** + * Ensure tables are responsive-ish + * + * @param domChildren + * @param parseOptions + */ const rewriteTable = (domChildren: DomElement[], parseOptions: HTMLReactParserOptions): ReactElement => { return createElement( 'div',