[WIP] Add better SEO support

[lee-dohm]

Applies to #122

• Author information - Was already working
• Logo - Half done, I need to know where to pull the actual logo from
• URL
• Page excerpt Done in Use a collection instead of pages for the articles #132

It appears the page excerpt part is going to be problematic. Jekyll extracts an excerpt automatically and this is what the jekyll-seo-tag gem relies on. The problem seems to be that Jekyll only extracts that excerpt on blog posts. Since all of the content in this site are normal pages, it isn't constructing the excerpt.

[bkeepers]

It appears the page excerpt part is going to be problematic. Jekyll extracts an excerpt automatically and this is what the jekyll-seo-tag gem relies on. The problem seems to be that Jekyll only extracts that excerpt on blog posts. Since all of the content in this site are normal pages, it isn't constructing the excerpt.

I actually ran into this on #27 as well. I'd love to avoid manually setting an excerpt for each page, but we may need to.

@benbalter @parkr if you have time, I'd love your thoughts on the best way to handle this.

[parkr]

@bkeepers Can we use collection documents instead of pages here? Collection documents give you automatic excerpts (same code as blog posts).

[kytrinyx]

@parkr if you could point me to some docs about collection documents I can make the change (sorry, first time Jekyll user).

[kytrinyx]

@parkr it looks like it's this: https://jekyllrb.com/docs/collections/#using-collections
I'll give it a whirl.

[kytrinyx]

@bkeepers @parkr I have no idea what I'm looking at here. Unless someone has time to give me a pointer I'm going to pass on it.

[benbalter]

If you don't do this, it should use site.github.url, which could account for things like HTTPS (in the works for GitHub-owned domains).

[kytrinyx]

I've started on a conversion to collections here: https://github.com/github/open-source-handbook/tree/kytrinyx-collections

The basic site structure appears to be ok, but I haven't figured out the navigation yet.

[kytrinyx]

Oh, and I bet the linting etc doesn't work with it yet.

[parkr]

@kytrinyx We could pair on it if you want! Each folder just prefixes with an underscore (docs becomes _docs). It would still output to /docs in the resulting site and you get access to it in Liquid as site.docs. Same with marketing (_marketing and site.marketing), and so forth. 😄
For each of these, you would specify them in the config file so Jekyll knows about them:

collections:
- docs
- marketing

If you want to change the permalink, you can specify metadata:

collections:
  docs:
    output: true
    permalink: /lol/:title
  marketing:
    output: true

:)

[kytrinyx]

@parkr Yes! I'd love to pair on it.

[kytrinyx]

(I tried that approach and got a bunch of 404s, btw)

[kytrinyx]

Here's what I have working:

# config
collections:
  articles:
    output: true
    permalink: /:path/

$ tree _articles
_articles/
├── getting-started
│   ├── branding.md
│   ├── defining.md
│   ├── legal.md
│   ├── preparing.md
│   └── setting-expectations.md
├── getting-started.md
├── marketing
│   ├── building-community.md
│   ├── measuring.md
│   └── spreading-word.md
├── marketing.md
├── sustaining
│   ├── best-practices.md
│   ├── healthy-communities.md
│   └── leadership.md
├── sustaining.md
├── troubleshooting
│   ├── burnout.md
│   ├── conduct.md
│   ├── contributions.md
│   ├── finding-consensus.md
│   └── getting-paid.md
└── troubleshooting.md

For the linter:

def docs
  (site.pages + site.collections["articles"].docs)
end

def pages
  docs.map { |doc| doc.to_liquid }
end

I have no idea how to translate the navigation:

<ul class="list-unstyled">
{% for path in item.contents %}
  {% assign subpage = site.pages | where: "path", path | first %}
  <li{% if page.url contains subpage.url %} class="selected"{% endif %}>
    <a class="d-block {% if page.url == subpage.url %} current{% endif %}"
      href="{{ subpage.url | prepend: site.baseurl }}">{{ subpage.title }}</a>
    {% if subpage.contents %}
      {% include contents.html item=subpage %}
    {% endif %}
  </li>
{% endfor %}
</ul>

I can't just swap out site.pages with site.articles.docs in this.

[kytrinyx]

OK, I think I got this working. Thanks @benbalter and @parkr for patient handholding. PR in #132.

[nayafia]

Closing this one. The most important thing we needed were meta descriptions, which was addressed in #132. Everything else was nice-to-haves/maybe-not-even-necessarys :)

Thanks everyone for your help!