fix: spacings, pagination, cli-ref

README.md

@@ -1,24 +1,12 @@
 # Welcome to the Blockstack documentation repo!
 
-This README explains the user cases, source file organization, and procedures for building the Blockstack documentation.  You can find the documentation at https://docs.blockstack.com
+This readme describes the project file organization and steps for building the Blockstack documentation site found at [docs.blockstack.com]()https://docs.blockstack.com).
 
-You can also make use of the **Edit this page on GitHub** link from any https://docs.blockstack.org page.
+You can also make use of the **Edit this page on GitHub** link found at the bottom of every page in the docs.
 
-## Authoring Environment Setup
+## Running and building the site locally
 
-When setting up your machine for the first time, run:
-
-```
-yarn
-```
-
-Then when authoring, run:
-
-```bash
-yarn dev
-```
-
-You can preview your changes by visiting `http://localhost:3000`
+If you are interested in contributing to the site and making changes, please refer to our [contributing guide here](https://docs.blockstack.org/ecosystem/contributing).
 
 ## Generated documentation
 
@@ -40,8 +28,7 @@ The `src/_data/cliRef.json` file is generated from the `blockstack-cli` subcomma
 
 ### Clarity Reference
 
-As of 8/12/19 Clarity is in the [develop](https://github.com/blockstack/blockstack-core/tree/develop) branch of core.  You can build the Clarity command line from the Docker image. `core/src/vm/docs/mod.rs`
-
+As of 8/12/19 Clarity is in the [develop](https://github.com/blockstack/blockstack-core/tree/develop) branch of core. You can build the Clarity command line from the Docker image. `core/src/vm/docs/mod.rs`
 
 1. Pull the latest developer preview from the Docker Hub.
 
@@ -61,11 +48,11 @@ As of 8/12/19 Clarity is in the [develop](https://github.com/blockstack/blocksta
 5. Build the docker image
 6. Run doc gen with the new image
 
-    ```
+   ```
    $ docker run --name docsbuild -it blockstack-test blockstack-core docgen | jsonpp > ~/repos/docs.blockstack/src/_data/clarityRef.json
-    ```
+   ```
 
-    This generates the JSON source files which are consumed through Liquid templates into markdown.
+   This generates the JSON source files which are consumed through Liquid templates into markdown.
 
 7. Rebuild the documentation site with Jekyll.
 
@@ -85,27 +72,27 @@ You can view [the source code](https://github.com/blockstack/blockstack-core/blo
 
 2. Start the Stacks Node test environment with a Bash shell.
 
-    ```bash
-    $ docker run -it -v $HOME/blockstack-dev-data:/data/ blockstack/blockstack-core:clarity-developer-preview bash
-    ```
+   ```bash
+   $ docker run -it -v $HOME/blockstack-dev-data:/data/ blockstack/blockstack-core:clarity-developer-preview bash
+   ```
 
-    The command launches a container with the Clarity test environment and opens a bash shell into the container.
+   The command launches a container with the Clarity test environment and opens a bash shell into the container.
 
 3. Run the clarity-cli in the shell.
 
-    ```bash
-    root@5b9798633251:/src/blockstack-core# clarity-cli
-    Usage: clarity-cli [command]
-    where command is one of:
-
-    initialize         to initialize a local VM state database.
-    mine_block         to simulated mining a new block.
-    get_block_height   to print the simulated block height.
-    check              to typecheck a potential contract definition.
-    launch             to launch a initialize a new contract in the local state database.
-    eval               to evaluate (in read-only mode) a program in a given contract context.
-    eval_raw           to typecheck and evaluate an expression without a contract or database context.
-    repl               to typecheck and evaluate expressions in a stdin/stdout loop.
-    execute            to execute a public function of a defined contract.
-    generate_address   to generate a random Stacks public address for testing purposes.
-    ```
+   ```bash
+   root@5b9798633251:/src/blockstack-core# clarity-cli
+   Usage: clarity-cli [command]
+   where command is one of:
+
+   initialize         to initialize a local VM state database.
+   mine_block         to simulated mining a new block.
+   get_block_height   to print the simulated block height.
+   check              to typecheck a potential contract definition.
+   launch             to launch a initialize a new contract in the local state database.
+   eval               to evaluate (in read-only mode) a program in a given contract context.
+   eval_raw           to typecheck and evaluate an expression without a contract or database context.
+   repl               to typecheck and evaluate expressions in a stdin/stdout loop.
+   execute            to execute a public function of a defined contract.
+   generate_address   to generate a random Stacks public address for testing purposes.
+   ```

package.json

@@ -95,6 +95,7 @@
     "start": "next telemetry disable && NODE_ENV=production next start",
     "clean:build-files": "rimraf .next && rimraf .cache",
     "dev": "yarn clean:build-files && next dev",
+    "build:cli-reference": "blockstack-cli docs > src/_data/cli-reference.json",
     "export": "next export",
     "lint": "yarn lint:eslint && yarn lint:prettier",
     "lint:eslint": "eslint \"src/**/*.{ts,tsx}\" -f unix",

src/common/data/cli-ref.ts

@@ -1,5 +1,5 @@
 import { convertRemoteDataToMDX } from '@common/data/mdx';
-import { cliReferenceData } from '../../_data/cliRef';
+import cliReferenceData from '../../_data/cli-reference.json';
 
 export const convertBlockstackCLIUsageToMdx = async () => {
   const transformed = cliReferenceData.map(entry => {

src/components/cli-reference.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
-import { cliReferenceData } from '@common/../_data/cliRef';
+import cliReferenceData from '../_data/cli-reference.json';
 import { Components } from '@components/mdx/mdx-components';
 import { Grid, Box, color } from '@blockstack/ui';
-import { border } from '@common/utils';
+import { border, onlyText } from '@common/utils';
 import hydrate from 'next-mdx-remote/hydrate';
 
 const styles = {
@@ -10,8 +10,20 @@ const styles = {
   overflowX: 'auto',
   overflowY: 'hidden',
   whiteSpace: 'pre',
+  display: 'inline-block',
 };
-const InlineCode = props => <Components.inlineCode {...styles} {...props} />;
+const cleanTheChildren = (children: any) => {
+  const text = onlyText(children).trim();
+  if (text.startsWith('$')) {
+    return text.replace('$', '');
+  }
+  return text;
+};
+const InlineCode = ({ children, ...rest }: any) => (
+  <Components.inlineCode {...styles} {...rest}>
+    {cleanTheChildren(children)}
+  </Components.inlineCode>
+);
 
 const ReferenceEntry = ({ entry, usage }) => (
   <>

src/components/icons/arrow-left.tsx

@@ -0,0 +1,11 @@
+import React from 'react';
+import { BaseSvg, SvgProps } from '@components/icons/_base';
+
+export const ArrowLeftIcon: SvgProps = props => (
+  <BaseSvg {...props}>
+    <path stroke="none" d="M0 0h24v24H0z" />
+    <line x1="5" y1="12" x2="19" y2="12" />
+    <line x1="5" y1="12" x2="11" y2="18" />
+    <line x1="5" y1="12" x2="11" y2="6" />
+  </BaseSvg>
+);

src/components/icons/arrow-right.tsx

@@ -0,0 +1,11 @@
+import React from 'react';
+import { BaseSvg, SvgProps } from '@components/icons/_base';
+
+export const ArrowRightIcon: SvgProps = props => (
+  <BaseSvg {...props}>
+    <path stroke="none" d="M0 0h24v24H0z" />
+    <line x1="5" y1="12" x2="19" y2="12" />
+    <line x1="13" y1="18" x2="19" y2="12" />
+    <line x1="13" y1="6" x2="19" y2="12" />
+  </BaseSvg>
+);

src/components/mdx/md-contents.tsx

@@ -261,9 +261,9 @@ export const MDContents: React.FC<any> = ({ pageTop: PageTop = null, headings, c
           width="100%"
           display={['none', 'none', 'none', 'block']}
         >
-          <Box position="sticky" top={0} pt="64px">
+          <Box position="sticky" top={0} pt={space('extra-loose')}>
             <Search mb={space('extra-loose')} />
-            {headings?.length ? <TableOfContents headings={headings} /> : null}
+            {headings?.length ? <TableOfContents limit={2} headings={headings} /> : null}
           </Box>
         </Box>
       ) : null}

src/components/pagination.tsx

@@ -8,10 +8,12 @@ import { Caption, Text, Link } from '@components/typography';
 import { useTouchable } from '@common/hooks/use-touchable';
 import { getHeadingStyles } from '@components/mdx/typography';
 import { css } from '@styled-system/css';
+import { ArrowRightIcon } from '@components/icons/arrow-right';
+import { ArrowLeftIcon } from '@components/icons/arrow-left';
 
 const FloatingLink: React.FC<any> = ({ href }) => (
   <NextLink href={`${href}`} passHref>
-    <Link position="absolute" size="100%" zIndex={2} as="a" />
+    <Link position="absolute" size="100%" left={0} top={0} zIndex={2} as="a" />
   </NextLink>
 );
 
@@ -53,7 +55,7 @@ const Description: React.FC<BoxProps> = props => (
 
 const Card: React.FC<any> = ({ children, ...rest }) => {
   const { bind, active, hover } = useTouchable({
-    behavior: 'link',
+    behavior: 'button',
   });
   return (
     <Flex
@@ -61,14 +63,12 @@ const Card: React.FC<any> = ({ children, ...rest }) => {
       width="100%"
       position="relative"
       border={border()}
-      borderRadius="12px"
+      borderRadius="6px"
       py={space('base')}
       px={space('base-loose')}
-      boxShadow={active ? 'low' : hover ? 'high' : 'mid'}
       transition={transition}
       justifyContent="center"
-      bg={active ? color('bg-light') : color('bg')}
-      transform={active ? 'translateY(3px)' : hover ? 'translateY(-5px)' : 'none'}
+      bg={color('bg')}
       {...bind}
       {...rest}
     >
@@ -82,7 +82,6 @@ const Pretitle: React.FC<BoxProps> = props => (
     display="block"
     color={color('text-caption')}
     transition={transition}
-    mb={space('base')}
     css={css({
       ...getHeadingStyles('h6'),
     })}
@@ -113,9 +112,20 @@ const PrevCard: React.FC<any> = React.memo(props => {
       {({ hover, active }) => (
         <>
           <FloatingLink href={prev.path} />
-          <Pretitle>Previous</Pretitle>
-          <Title isHovered={hover || active}>{getTitle(prev)}</Title>
-          {prev.description && <Description>{prev.description}</Description>}
+          <Flex position="relative" mb={space('base-tight')} align="center">
+            <Pretitle
+              left={hover || active ? '18px' : 0}
+              bg={color('bg')}
+              position="relative"
+              zIndex={2}
+            >
+              Previous
+            </Pretitle>
+            <Box position="absolute" left={0} color={color('text-caption')} pt="2px">
+              <ArrowLeftIcon size="14px" />
+            </Box>
+          </Flex>
+          <Title isHovered={hover}>{getTitle(prev)}</Title>
         </>
       )}
     </Card>
@@ -131,9 +141,20 @@ const NextCard: React.FC<any> = React.memo(props => {
       {({ hover, active }) => (
         <>
           <FloatingLink href={next.path} />
-          <Pretitle>Next</Pretitle>
-          <Title isHovered={hover || active}>{getTitle(next)}</Title>
-          {next.description && <Description>{next.description}</Description>}
+          <Flex position="relative" mb={space('base-tight')} align="center">
+            <Pretitle
+              right={hover || active ? '18px' : 0}
+              bg={color('bg')}
+              position="relative"
+              zIndex={2}
+            >
+              Next
+            </Pretitle>
+            <Box position="absolute" right={0} ml="4px" color={color('text-caption')} pt="2px">
+              <ArrowRightIcon size="14px" />
+            </Box>
+          </Flex>
+          <Title isHovered={hover}>{getTitle(next)}</Title>
         </>
       )}
     </Card>

src/components/side-nav.tsx

@@ -28,7 +28,7 @@ const Wrapper: React.FC<BoxProps & { containerProps?: BoxProps }> = ({
         maxHeight={`calc(100vh - 60px)`}
         overflow="auto"
         top={0}
-        pt="64px"
+        pt={space('extra-loose')}
         {...containerProps}
       >
         {children}