Merge pull request #1491 from spotify/mob/techdocs-landing-page

Mob/techdocs landing page

plugins/techdocs/src/reader/components/DocsCard.tsx

@@ -1,79 +0,0 @@
-/*
- * Copyright 2020 Spotify AB
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import React, { FC } from 'react';
-import { Button, Card, Chip, Typography, makeStyles } from '@material-ui/core';
-
-const useStyles = makeStyles(theme => ({
-  header: {
-    color: theme.palette.common.white,
-    padding: theme.spacing(2, 2, 6),
-    backgroundImage:
-      'linear-gradient(-137deg, rgb(25, 230, 140) 0%, rgb(29, 127, 110) 100%)',
-  },
-  content: {
-    padding: theme.spacing(2),
-  },
-  description: {
-    height: 175,
-    overflow: 'hidden',
-    textOverflow: 'ellipsis',
-  },
-  footer: {
-    display: 'flex',
-    flexDirection: 'row-reverse',
-  },
-}));
-
-type DocsCardProps = {
-  description: string;
-  tags?: string[];
-  title: string;
-  type?: string;
-  label: string;
-  onClick?: () => void;
-};
-export const DocsCard: FC<DocsCardProps> = ({
-  description,
-  tags,
-  title,
-  type,
-  label,
-  onClick,
-}) => {
-  const classes = useStyles();
-
-  return (
-    <Card>
-      <div className={classes.header}>
-        {type ?? <Typography variant="subtitle2">{type}</Typography>}
-        <Typography variant="h6">{title}</Typography>
-      </div>
-      <div className={classes.content}>
-        {tags?.map(tag => (
-          <Chip label={tag} key={tag} />
-        ))}
-        <Typography variant="body2" paragraph className={classes.description}>
-          {description}
-        </Typography>
-        <div className={classes.footer}>
-          <Button onClick={onClick} color="primary">
-            {label}
-          </Button>
-        </div>
-      </div>
-    </Card>
-  );
-};

plugins/techdocs/src/reader/components/Reader.tsx

@@ -20,16 +20,17 @@ import { useAsync } from 'react-use';
 import { useLocation, useParams, useNavigate } from 'react-router-dom';
 
 import { Grid } from '@material-ui/core';
-import { Header, Content } from '@backstage/core';
+import { Header, Content, ItemCard } from '@backstage/core';
 
 import transformer, {
   addBaseUrl,
   rewriteDocLinks,
   addEventListener,
+  removeMkdocsHeader,
+  modifyCss,
 } from '../transformers';
 import { docStorageURL } from '../../config';
 import URLParser from '../urlParser';
-import { DocsCard } from './DocsCard';
 
 const useFetch = (url: string) => {
   const state = useAsync(async () => {
@@ -77,6 +78,16 @@ export const Reader = () => {
         rewriteDocLinks({
           componentId,
         }),
+        modifyCss({
+          cssTransforms: {
+            '.md-main__inner': [{ 'margin-top': '0' }],
+            '.md-sidebar': [{ top: '0' }, { width: '20rem' }],
+            '.md-typeset': [{ 'font-size': '1rem' }],
+            '.md-nav': [{ 'font-size': '1rem' }],
+            '.md-grid': [{ 'max-width': '80vw' }],
+          },
+        }),
+        removeMkdocsHeader(),
       ]);
 
       divElement.shadowRoot.innerHTML = '';
@@ -93,39 +104,37 @@ export const Reader = () => {
 
   return (
     <>
-      {componentId ? (
-        <div ref={shadowDomRef} />
-      ) : (
-        <>
-          <Header
-            title="Documentation"
-            subtitle="Documentation available in Backstage"
-          />
+      <Header
+        title={componentId ?? 'Documentation'}
+        subtitle={componentId ?? 'Documentation available in Backstage'}
+      />
 
-          <Content>
-            <Grid container>
-              <Grid item xs={12} sm={6} md={3}>
-                <DocsCard
-                  onClick={() => navigate('/docs/mkdocs')}
-                  tags={['Developer Tool']}
-                  title="MkDocs"
-                  label="Read Docs"
-                  description="MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. "
-                />
-              </Grid>
-              <Grid item xs={12} sm={6} md={3}>
-                <DocsCard
-                  onClick={() => navigate('/docs/backstage-microsite')}
-                  tags={['Service']}
-                  title="Backstage"
-                  label="Read Docs"
-                  description="Getting started guides, API Overview, documentation around how to Create a Plugin and more. "
-                />
-              </Grid>
+      <Content>
+        {componentId ? (
+          <div ref={shadowDomRef} />
+        ) : (
+          <Grid container>
+            <Grid item xs={12} sm={6} md={3}>
+              <ItemCard
+                onClick={() => navigate('/docs/mkdocs')}
+                tags={['Developer Tool']}
+                title="MkDocs"
+                label="Read Docs"
+                description="MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. "
+              />
             </Grid>
-          </Content>
-        </>
-      )}
+            <Grid item xs={12} sm={6} md={3}>
+              <ItemCard
+                onClick={() => navigate('/docs/backstage-microsite')}
+                tags={['Service']}
+                title="Backstage"
+                label="Read Docs"
+                description="Getting started guides, API Overview, documentation around how to Create a Plugin and more. "
+              />
+            </Grid>
+          </Grid>
+        )}
+      </Content>
     </>
   );
 };

plugins/techdocs/src/reader/transformers/index.ts

@@ -17,6 +17,8 @@
 export * from './addBaseUrl';
 export * from './rewriteDocLinks';
 export * from './addEventListener';
+export * from './removeMkdocsHeader';
+export * from './modifyCss';
 
 export type Transformer = (dom: Element) => Element;
 

plugins/techdocs/src/reader/transformers/modifyCss.ts

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Transformer } from './index';
+
+type ModifyCssOptions = {
+  // Example: { '.md-container': { 'marginTop': '10px' }}
+  cssTransforms: { [key: string]: { [key: string]: string }[] };
+};
+
+export const modifyCss = ({ cssTransforms }: ModifyCssOptions): Transformer => {
+  return dom => {
+    Object.entries(cssTransforms).forEach(([cssSelector, cssChanges]) => {
+      const elementsToChange = Array.from(
+        dom.querySelectorAll<HTMLElement>(cssSelector),
+      );
+      if (elementsToChange.length < 1) return;
+
+      cssChanges.forEach(changes => {
+        elementsToChange.forEach((element: HTMLElement) => {
+          Object.entries(changes).forEach(([cssProperty, cssValue]) => {
+            element.style.setProperty(cssProperty, cssValue);
+          });
+        });
+      });
+    });
+
+    return dom;
+  };
+};

plugins/techdocs/src/reader/transformers/removeMkdocsHeader.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Transformer } from './index';
+
+export const removeMkdocsHeader = (): Transformer => {
+  return dom => {
+    // Remove the header
+    dom.querySelector('.md-header')?.remove();
+
+    return dom;
+  };
+};