Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Improved SEO (meta tags support)

See original GitHub issue

Feature request

What problem does this feature solve?

It improves SEO of pages generated by Docsify. It makes it easier for search engines to find the relevant content, and when a user shares a link to a Docsify page, the rendered preview is more accurate (title, description and image).

Example (diff pages, same SEO 😢 ):

What does the proposed API look like?

Marp allows you to write slides using Markdown, and each file has a small header like this:

---
marp: true
title: Marp CLI example
description: Hosting Marp slide deck on the web
theme: uncover
paginate: true
---

Docsify could have something similar that would allow us to define the meta tags of each page. Example:

---
<!-- Primary Meta Tags -->
meta-title: Site title: Page title
meta-description: This is the summary that appears on search engine results or preview links
<!-- Open Graph -->
meta-og-type: 
meta-og-url: 
meta-og-title: 
meta-og-description: 
meta-og-image: https://yourdomain.com/path/to/image.jpg
<!-- Twitter -->
meta-twitter-card: 
meta-twitter-url: 
meta-twitter-title: 
meta-twitter-description: 
meta-twitter-image: https://yourdomain.com/path/to/image.jpg
---

# Page title

And the _rest_ of the page.

I think a syntax like this would be good enough for us. I would say the first two fields are the MVP, as that works everywhere.
Then Open Graph would be helpful, because it allows you to define an image.
And finally, with the lowest priority/importance, the Twitter meta tags, because if Twitter can’t find them it will fallback to the Open Graph tags.

How should this be implemented in your opinion?

I checked if it was possible to hack it with the current Docsify version by hardcoding HTML tags in the .md file.

<!-- markdownlint-disable MD033 -->
<!-- SEO tags -->
<title>(TITLE) (SEPARATOR) Title of this page</title>
<meta name="title" content="(TITLE) (SEPARATOR) Title of this page">
<meta name="description" content="A description that is specific to this page.">

# TITLE_HERE

failed attempt

It didn’t work. Those tags were added inside <body> ... <article>, but we need them to exist in the <head> section.

I propose this flow:

When Docsify reads a Markdown file, it checks if it has a header.
If it doesn’t, then everything works as is.
If it has, it will read each key (e.g. meta-title) and override it’s value.

Example:

Docsify detects a header. One key is meta-dummy. Docsify doesn’t know how to handle this key, so it skips it. The next key is meta-title. Docsify knows how to handle this, so it goes to head.meta.title and replaces the default value with the value in the file header.

Are you willing to work on this yourself?

I don’t think I have enough JS and Docsify knowledge to develop this feature. But I can (beta) test it!

Issue Analytics

State:
Created 3 years ago
Reactions:3
Comments:20 (16 by maintainers)

Top GitHub Comments

1reaction

jcayzaccommented, Nov 27, 2020

You can trivially inject meta like this:

index.html

  <title>Foo</title>
+ <meta name="description" content>
+ <meta name="keywords" content>

SEO plugin

'use strict';

/*
 * Update the page info based on frontmatter data or on the configurated
 * generator.
 */
(function (window) {
  function meta(name, content) {
    document.querySelector(`meta[name="${name}"]`).content = content || ''
  }

  function plugin(hook, vm) {
    const refreshInfo = () => {
      const { config, route, frontmatter } = vm
      const { description, keywords } = frontmatter || {}
      const entries = { description, keywords }

      for (const key in entries) {
        var value = entries[key]

        if (value === undefined) {
          const defaultValue = config.seo?.[key]
          if (typeof defaultValue === 'function') value = defaultValue(route, frontmatter || {})
          else value = defaultValue
        }

        meta(key, value)
      }
    }
    
    hook.init(refreshInfo)
    hook.doneEach(refreshInfo)
  }

  window.$docsify = window.$docsify || {}
  window.$docsify.plugins = window.$docsify.plugins || []
  window.$docsify.plugins.push(plugin)
})(this)

Config

Optional: For each meta, provide either a string or a function that returns the value.

 window.$docsify = Object.assign(window.$docsify || {}, {
+  seo: {
+    description: (route, frontmatter) => {
+      if (route.path.startsWith('/ja/')) return `一般的な説明`
+      else return `Some default description`
+    },
+    keywords: `foo, bar, baz`,
+  },
   pagination: {

1reaction

jhildenbiddlecommented, Jun 26, 2020

We’re talking about different things.

Q: Can we improve SEO for docsify sites? A1: For server side rendering? Yes, using <meta> tags, possibly sooner than later. A2: For static site generation? Yes, using <meta> tags, but not until we have SSG. A3: For client-side rendering? Possibly. We aren’t sure if/how <meta> tags created and injected on the client affect SEO.

Google Structured Data was offered as a way to address the uncertainty of A3 and address @trusktr’s “Does changing the meta tags at runtime (each time we change pages) have any effect on the browser?” question. Google’s documentation states specifically that this SEO-related information can be generated on the client, which would allow us to improve SEO for client-side only docsify sites. It’s not about a new syntax; it’s about improving SEO for the sites that need it most (client-side rendering) that also (I assume) make up the vast majority of docsify users. For the record, I’m not proposing we should go this route, only that we could explore it if client-side <meta> tags won’t work.

After a little digging, it looks like client-side generated <meta> tags might actually work (which would be awesome). I think I can do some tests using a custom plugin to mimic client-side YAML-to-Meta conversion, then check the results using Google’s URL Inspection Tool to see how Google indexes the page. If we can inject <meta> tags on the client instead of using Google Structured Data, that would be great (and preferreable).