WIP: Expand/improve documentation

README.md

@@ -4,7 +4,7 @@ Create a Gatsby site that includes blog posts, Markdown pages, and [Nautilus](ht
 
 ## 🚀 Quick start
 
-1.  **Create a Gatsby site.**
+1. **Create a Gatsby site.**
 
     Use the Gatsby CLI to create a new site, specifying the `ghost-ship` as your starter:
 
@@ -13,7 +13,7 @@ Create a Gatsby site that includes blog posts, Markdown pages, and [Nautilus](ht
     npx gatsby new my-site https://github.com/octopusthink/ghost-ship
     ```
 
-2.  **Start the development server.**
+2. **Start the development server.**
 
     Navigate into your new site’s directory, install the dependencies, and start the development server:
 
@@ -22,10 +22,76 @@ Create a Gatsby site that includes blog posts, Markdown pages, and [Nautilus](ht
     yarn start # or `npm start` if you use `npm`.
     ```
 
-3.  **Open the source code and start editing!**
+3. **Open the source code and start editing!**
 
     Your site is now running at [`http://localhost:8000/`](http://localhost:8000/)!
 
+## 🚧 Build your site
+
+Here are a few things we recommend starting with:
+
+### Configure your settings
+
+Set your site's configurations by editing your `data/SiteConfig.js` file.
+
+When you make changes, you'll need to restart the server to see these changes reflected.
+
+### Add logos and favicons
+
+Most of your images should go in the `/src/images` folder. Images in this folder will be processed by Gatbsy to lazy-load and generally be optimised for fast-and-friendly loading. If you have issues with images used, try moving them to the `/static` folder!
+
+Ghost Ship is already set up for a favicon. Just make a favicon.png and save it to './static/favicon.png'. The recommended size for the file is 1500x1500px.
+
+### Create a custom theme
+
+To add a custom theme, first create a [Nautilus](https://nautilus.octopusthink.com/) theme file. (Documentation for themeing is coming soon, but for now copying the [default theme](https://github.com/octopusthink/nautilus/blob/master/src/themes/nautilus/index.js) file will do the trick, and modify values as needed.) You can put it anywhere you like, but we recommend `data/theme.js`.
+
+Then, open up `components/NautilusWrapper`, import the theme, and pass it as a prop to Nautilus:
+
+```jsx
+import theme from 'data/theme';
+
+<Nautilus theme={theme}>
+```
+
+### Configure content types
+
+### Add some content
+
+### Modify your CSS
+
+### Launch your site
+
+## ✨What's next
+
+### Using the design system
+
+To get up and running faster, Ghost Ship uses the [Nautilus](https://nautilus.octopusthink.com) design system. Since Nautilus is still very much in its infancy, it's pulling from the latest changes made to the `master` GitHub branch, rather than the published version.
+
+To pull the latest changes, uninstall and reinstall the Nautilus dependency:
+
+```bash
+npm uninstall nautilus && npm install --save octopusthink/nautilus
+```
+
+## SEO
+
+### Page frontmatter
+
+There are a few SEO-specific properties you can set for any page or other content type:
+
+`metaDescription:` For setting the meta description.
+`thumbnail`: For setting a thumbnail image to appear when shared on social media.
+`canonical`: For setting the canonical url.
+
+These are all optional—don't use them if you don't need them!
+
+### Thumbnail images
+
+For each page, you can set a custom thumbnail that will be used when sharing on Twitter, Facebook, etc. If no thumbnail is set, the page will use the fallback thumbnail, as defined in your `SiteConfig.js`.
+
+We recommend using the size 630x1200 for maximum compatibility. These images should be stored in the `static/` directory.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.

data/SiteConfig.js

@@ -14,20 +14,25 @@ const config = {
   siteUrl: 'https://yourdomain.com',
   // Prefixes all links. For cases when deployed to example.github.io/gatsby-advanced-starter/.
   pathPrefix: '/',
-  // Website description used for RSS feeds/meta description tag.
+  // Website description used for RSS feeds/meta description tag. 170 char.
   siteDescription:
     'Ghost ship is a Gatsby starter that offers blogging, optimised images, a portfolio, and more.',
   // Path to the RSS file.
   siteRss: '/blog/rss.xml',
   twitter: '@tweettweet',
   // Copyright string for the footer of the website and RSS feed.
   copyright: `Copyright © ${new Date().getFullYear()}. Your name here.`,
+  // Fallback image used when sharing to social sites.
+  defaultImage: '/og-images/default.png',
+  imageHeight: '630',
+  imageWidth: '1200',
 
   /* ------------ Blog Settings ------------ */
   blogTitle: 'Our Blog',
   blogDescription: 'The blog of Ghost Ship, famed for its speed.',
   blogSummary:
     'AKA our blog, in which we talk about spooky ships and fast websites. It is quite the good time!',
+  blogUrl: '/blog/',
   dateFormat: 'D MMMM YYYY',
   enableBlogAuthors: true,
   enableBlogTags: true,

gatsby-config.js

@@ -125,14 +125,18 @@ if (config.matomoOptions && Object.keys(config.matomoOptions).length) {
 
 module.exports = {
   siteMetadata: {
-    title: config.siteTitle,
-    description: config.siteDescription,
     author: config.twitter,
-    siteUrl: config.siteUrl,
-    copyright: config.copyright,
-    blogTitle: config.blogTitle,
     blogDescription: config.blogDescription,
     blogSummary: config.blogSummary,
+    blogTitle: config.blogTitle,
+    copyright: config.copyright,
+    defaultImage: config.defaultImage,
+    description: config.siteDescription,
+    imageHeight: config.imageHeight,
+    imageWidth: config.imageWidth,
+    language: config.language,
+    siteUrl: config.siteUrl,
+    title: config.siteTitle,
   },
   plugins: [
     {

src/components/SEO/index.js

@@ -10,73 +10,159 @@ import React from 'react';
 import Helmet from 'react-helmet';
 import { useStaticQuery, graphql } from 'gatsby';
 
-const SEO = (props) => {
-  const { description, homepage, lang, meta, title } = props;
-  const { site } = useStaticQuery(graphql`
-    query {
-      site {
-        siteMetadata {
-          title
-          description
-          author
+const outputIfSet = (valueToCheck, objectToOutput) => {
+  if (!valueToCheck) {
+    return {};
+  }
+
+  return { ...objectToOutput };
+};
+
+function SEO(props) {
+  const {
+    article,
+    canonical,
+    description,
+    homepage,
+    image,
+    lang,
+    meta,
+    modifiedTime,
+    pathname,
+    publishedTime,
+    tags,
+    title,
+  } = props;
+  const { site } = useStaticQuery(
+    graphql`
+      query {
+        site {
+          siteMetadata {
+            author
+            defaultImage
+            description
+            imageHeight
+            imageWidth
+            language
+            siteUrl
+            title
+          }
         }
       }
-    }
-  `);
+    `,
+  );
 
-  const metaDescription = description || site.siteMetadata.description;
-  let pageTitle = `${title} · ${site.siteMetadata.title}`;
+  // Inverse the order of site & page titles on homepage only.
+  // TODO: Try to use Helmet's titleTemplate and/or automatic detection.
+  let pageDisplayTitle = `${title} · ${site.siteMetadata.title}`;
   if (homepage) {
-    pageTitle = `${site.siteMetadata.title} · ${title}`;
+    pageDisplayTitle = `${site.siteMetadata.title} · ${title}`;
   }
 
+  const seo = {
+    description: description || site.siteMetadata.description,
+    lang: lang || site.siteMetadata.language,
+    image: `${site.siteMetadata.siteUrl}${image || site.siteMetadata.defaultImage}`,
+    imageHeight: site.siteMetadata.imageHeight,
+    imageWidth: site.siteMetadata.imageWidth,
+    modifiedTime,
+    publishedTime,
+    siteName: site.siteMetadata.title,
+    tags,
+    title,
+    type: article ? `article` : `website`,
+    url: canonical || `${site.siteMetadata.siteUrl}${pathname || '/'}`,
+  };
+
   return (
     <Helmet
       htmlAttributes={{
-        lang,
+        lang: seo.lang,
       }}
       meta={[
         {
           name: `description`,
-          content: metaDescription,
+          content: seo.description,
+        },
+        {
+          property: `og:site_name`,
+          content: seo.siteName,
         },
         {
           property: `og:title`,
-          content: title,
+          content: seo.title,
         },
         {
           property: `og:description`,
-          content: metaDescription,
+          content: seo.description,
         },
         {
           property: `og:type`,
-          content: `website`,
+          content: seo.type,
         },
+        {
+          property: `og:url`,
+          content: seo.url,
+        },
+        {
+          property: `og:locale`,
+          content: seo.lang,
+        },
+        {
+          property: `og:image`,
+          content: seo.image,
+        },
+        {
+          property: `og:image:width`,
+          content: seo.imageWidth,
+        },
+        {
+          property: `og:image:height`,
+          content: seo.imageHeight,
+        },
+        outputIfSet(article && seo.publishedTime, {
+          property: `article:published_time`,
+          content: seo.publishedTime,
+        }),
+        outputIfSet(article && seo.modifiedTime, {
+          property: `article:modified_time`,
+          content: seo.modifiedTime,
+        }),
+        outputIfSet(article && seo.tags, {
+          property: `article:tags`,
+          content: seo.tags,
+        }),
         {
           name: `twitter:card`,
-          content: `summary`,
+          content: `summary_large_image`,
         },
         {
           name: `twitter:creator`,
           content: site.siteMetadata.author,
         },
         {
           name: `twitter:title`,
-          content: title,
+          content: seo.title,
         },
         {
           name: `twitter:description`,
-          content: metaDescription,
+          content: seo.description,
+        },
+        {
+          name: `twitter:image`,
+          content: seo.image,
         },
       ].concat(meta)}
     >
-      <title>{pageTitle}</title>
+      <title>{pageDisplayTitle}</title>
+      <link rel="canonical" href={seo.url} />
     </Helmet>
   );
-};
+}
 
 SEO.defaultProps = {
-  lang: `en-GB`,
+  // If this prop is `undefined`, `siteConfig.language` will be used as a fallback.
+  lang: undefined,
   meta: [],
   description: ``,
 };

src/components/SiteFooter/index.js

@@ -1,7 +1,29 @@
+import { css } from '@emotion/core';
+import { Paragraph } from '@octopusthink/nautilus';
 import React from 'react';
 
+import config from 'data/SiteConfig';
+
+import config from 'data/SiteConfig';
+
 const SiteFooter = () => {
-  return <footer></footer>;
+  return (
+    <footer
+      css={css`
+        border-top: 2px solid;
+        margin-top: 4.8rem;
+        margin: 0 auto;
+        max-width: ${config.contentWidth};
+        max-width: ${config.siteContentWidth};
+        padding: 2.4rem 0;
+        text-align: center;
+      `}
+    >
+      <Paragraph small light>
+        {config.copyright}
+      </Paragraph>
+    </footer>
+  );
 };
 
 export default SiteFooter;

src/content/pages/about.mdx

@@ -2,7 +2,7 @@
 title: Who we are
 summary: All about us.
 summaryExtra: A little extra summary.
-metaDescription: This goes in the meta description tag.
+metaDescription: We are a group of humans who like ocean-going creatures, except for maybe sea crocodiles.
 ---
 
 We are _very_ cool.