octopusthink / ghost-ship

A Gatsby starter template for websites & blogs. Designed for accessibility and SEO-friendliness.

Ghost Ship Gatsby Starter

Create a Gatsby site that includes blog posts, Markdown pages, and Nautilus.

🚀 Quick start

1. Create a Gatsby site.

   Use the Gatsby CLI to create a new site, specifying the ghost-ship as your starter:

   # Create a new Gatsby site using the ghost-ship starter.
   npx gatsby new my-site https://github.com/octopusthink/ghost-ship

2. Start the development server.

   Navigate into your new site’s directory, install the dependencies, and start the development server:

   cd my-site/
   yarn start # or `npm start` if you use `npm`.

3. Open the source code and start editing!

   Your site is now running at http://localhost:8000/!

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 file for details.

ghost-ship's Issues

Add super-simple site structure

This will both show how to use CSS in a site, and also avoid this super ugly thing:

Just some sort of max-width on the main content area should do the trick.

Switch to non-relative import paths

So

import App from ‘./app’;

should be

import App from ‘./App’;

otherwise things will panic and fail to build. Sadface.

While we're at it, it'd be good to switch to non-relative paths as per https://github.com/octopusthink/octopusthink.com/pull/88

Tags should display on blog posts

Right now, we use tags but they aren't revealed anywhere, so you can't browse to the tag archive or filter posts. This could be useful for both posts and portfolios.

Ensure page metadata is unique for each page

Summaries of blog posts (see #1) and potentially other pages as well may help us avoid this, but right now we do this:

<meta name="description" content={siteDescription} />

I'm fairly certain that the meta description value needs to be unique and specific to each individual page.

https://neilpatel.com/blog/meta-description-magic/

It's possible that we should also allow for this description to be set in frontmatter for every page/post/whatever, separately from the summary, so that those who care about such things can tweak it to their needs.

Quit using Gatsby config values for site widths

It's more annoying and harder to work with, and since we're baking these values into Nautilus anyway it makes a whole lot more sense to keep them there.

Relies on this Nautilus change: octopusthink/nautilus#194

Better display of metadata (dates, authors, etc) for blog posts

I've started this a bit on the Octopus Think site, but it still needs more work!

A proper byline for author credit might be nice, for instance, and we'll want to show tags somewhere as well (see also #7).

Allow for easily disabling blog and portfolio

This was kind of addressed via #12, but I was definitely expecting to be able to do more configuration work (ie, stripping out the blog and portfolio) from the config file, which isn't the case.

So for instance, I can set authors and tags to false:

enableBlogAuthors: false,
enableBlogTags: false,

...but if I delete the authors or tags yaml files, I get a whole slew of errors, and there's no way to say I don't want or need a blog at all. (Or a portfolio!)

Looking in utils/settings.js (which I think is intending to act as a sort of automatic settings file, although that confused me too so it could use some commenting) it looks as though deleting the blog and portfolio directories will do the trick. When I tried this, I seemed to bork everything:

ERROR

UNHANDLED REJECTION Cannot read property 'resolve' of undefined
TypeError: Cannot read property 'resolve' of undefined

How does one remove the blog and portfolio features from a Ghost Ship site?

Add search!

This is something I'd totally dig for 404 pages, for instance, and it's a teensy bit complex to do with Gatsby (which do I choose? how do I start? etc)

https://www.gatsbyjs.org/docs/adding-search/

Is this something we could add to the boilerplate?

Create a portfolio archive page

Right now, there are portfolio pages, but no archive to show them all. We'll probably want to include an archive template, which may warrant some additional metadata for portfolio types.

Off the top of my head, I'd like to include a summary as per #1, and a thumbnail image of some sort, but we may also want to include tags like the blog posts do.

Page titles should include the site name

The page titles (as passed to Helmet) should always include the site name as a trailing value, so instead of:

• Uh-oh
• Blog Posts
• Home

we'd have:

• Uh-oh · Octopus Think
• Blog Posts · Octopus Think
• Home · Octopus Think

I'm partial to a middot ( · ) as a separator, but I'm also fine with a pipe ( | ).

Some of those default titles may need fine-tuning outside of that, too. ;)

Show copyright string in site footer

The SiteConfig file indicates a copyright string will be shown in the footer:

// Copyright string for the footer of the website and RSS feed.

We should show it!

Site title should be inverted on homepage

Basically so this:

Welcome! · My Site

becomes

My Site · Welcome!

See https://github.com/octopusthink/octopusthink.com/pull/92 for some context.

octopusthink.com does this by passing a homepage prop to the SEO component, which works because the homepage is using a different template than the other pages. So we basically have two options here:

1. Always use a separate template for the homepage. (Increases complexity needlessly for some uses.)
2. Dynamically determine if we're on the homepage (maybe by inspecting the URL or the source filename?) and page the prop accordingly.

No. 2 seems like the much less fragile option here, but if it isn't a possible technically a better alternative might be to manually set a "homepage" flag to true in the homepage's front matter.

Setting blog options to false breaks a generated site

If you set enableBlogAuthors or enableBlogTags to false in your SiteConfig, Gatsby freaks out:

 ERROR #11321  PLUGIN

"gatsby-node.js" threw an error while running the createPages lifecycle:

Field "authors" must not have a selection since type "[String]" has no subfields.

GraphQL request:11:23
10 |             fields {
11 |               authors {
   |                       ^
12 |                 id,Field "tags" must not have a selection since type "[String]" has no subfields.

GraphQL request:21:20
20 |               title
21 |               tags {
   |                    ^
22 |                 id

failed createPages - 0.072s
success createPagesStatefully - 0.035s
success onPreExtractQueries - 0.003s
success update schema - 0.022s

 ERROR #85909  GRAPHQL

Field "tags" must not have a selection since type "[String]" has no subfields

File: src/templates/Blog/index.js:87:18

Looks like the queries may need to be adjusted to account for these settings.

As a sidenote, I'm okay with not allowing people to remove tags and authors from the blog, since this is probably rare—most people who want a blog would be likely to want certainly tags, but possibly authors as well. And having authors in a set file, even if there's only a single author, makes it more straightforward to show an author bio box or similar.

See also #25.

Strip out Octopus-Think specifics

Because, obviously.

Ensure everything has proper landmarks out of the box

main, main should have ID of content

Improve archive page design & make generic component

Just so it's a bit nicer and more readable out of the box. Using Nautilus' Card component, once available, would be a nice touch.

Given that both blog posts and archives will use an archive page template (and tags will borrow from the design as well), we may want to include some sort of reusable generic archive component or template, that could then be extended or modified for specific usage. For instance, I may want blog archives and portfolio archives to look and work more or less the same way, but show thumbnails only for portfolio archives.

Add an SEO component

...backport from https://github.com/octopusthink/octopusthink.com/issues/41 so I never have to think about SEO ever again.

Automatically include Nautilus wrapper

Probably using this approach: https://github.com/octopusthink/octopusthink.com/commit/98b3bce2e48ffd6c3cefc179fb14bc75f06176dc

Add some kind of sitemap component

An XML sitemap would be useful for SEO or whatnot, but it would also be good to include a visual sitemap for the 404 page out of the box, along with a search (#2), so users have an easier time finding what they're looking for.

https://www.gatsbyjs.org/docs/creating-a-sitemap/
https://ghost.org/blog/advanced-sitemaps-gatsby/

Add SkipLink component

Consider adding summaries/excerpts for blog posts

One of the first things I did with the Octopus Think website was add summaries to blog posts:

(These could be called "summary" or "excerpt" or something else?)

These are commonly used certainly in WordPress blogs, and can be useful in lots of places editorially. They could also form the meta for that page.

Use smart quotes by default

Ensure pages don't output empty <h1>s

All pages are currently outputting empty <h1> tags:

Not great for accessibility! It looks like we're passing a bunch of data to the PageHeader component, but the component has been simplified to only show children as a prop.

So instead of:
<PageHeader pageTitle={title} summary={summary} description={description} />
the fix would be to use:
<PageHeader>{title}</PageHeader>

Alternatively, we could refine the PageHeader component to accept more props. This tends to be a common pattern I use for sites, so I'm tempted to opt for the latter approach, although I'm happy to hear dissenting opinions. @tofumatt, thoughts?

Add a default page menu component

This is always annoying to do, so it would be good to provide something robust out of the box.

Backport from octopusthink.com once https://github.com/octopusthink/octopusthink.com/issues/51 is figured out, and maybe allow for dynamic pages? Or just select the pages that are already there. Either way, no 404s.

Improve default content

I was just starting to file an issue to request MDX, and then I realised we'd already brought that over... but the file I was editing was a .md and so I assumed it wasn't there.

Let's maybe use the default starter content as a way to teach people (including myself) how to use the starter.

So, for instance:

• Show both Markdown and MDX in use, and be explicit with examples.
• Show more examples of different content!
• import { Button, Heading, Link, Paragraph } from '@octopusthink/nautilus' so I don't have to search + copy
• Show links to blog and portfolio (and maybe also the 404 page listing? see also #23) along with how to add, remove, or change content (#25)
• Link back to help docs if and when we have them, or at least GitHub!
• Provide some suggested starting edits: modify SiteSettings.js, add a Nautilus theme, add logos & icons, add a page, etc. (This should also go back to the docs.)

Add a sitemap component

Backport from #3

Improve the default 404 page

Probably go for functional over clever, but including search (#2) and a sitemap (#3) along with some better messaging would be a good first step.

See also:
https://optinmonster.com/best-404-page-examples/
https://www.creativebloq.com/web-design/best-404-pages-812505
https://blog.hubspot.com/blog/tabid/6307/bid/33766/10-clever-website-error-messages-from-creative-companies.aspx

Allow for blog, portfolio, etc. pages to be optional

@sarahmonster was working on https://github.com/octopusthink/funfactsaboutoctopus.es and found that simply removing the src/content/blog/ folders wasn't sufficient to hide the blog functionality. We should separate the queries we make for blog posts vs pages and only build/render the blog content if there are posts to make.

Prettier dates by default

Ideally these would use a site config, but let's avoid showing this out of the box:

BOOOOOOOOO.

I'm not sure if it'd be best to use GraphQL here or a third-party library.

https://www.gatsbyjs.org/docs/querying-with-graphql/#formatting-dates