Support for jekyll's `excerpt` property

Question

Support for jekyll's `excerpt` property

Closed this issue 7 years ago · 19 comments

Hey @jonschlinkert thanks for writing gray-matter. I'm migrating Electron's website away from ruby and Jekyll to a node server, and gray-matter has become an instrumental piece of that transition, by way of tree-hugger.

Jekyll has this concept of excerpts which we are making use of in our site. The gist is that they extract initial content of a document. By default it's the first paragraph, but can be overridden with an excerpt_separator property.

In Electron's specific case the separator is ---, also known as <hr>.

Would you be interested in supporting excerpt extraction in gray-matter? If so, I'd be happy to work on a PR.

Answer 1 · 2017-06-26T08:08:39.000Z

Would you be interested in supporting excerpt extraction in gray-matter? If so, I'd be happy to work on a PR.

absolutely! love the idea, and I think it makes sense here. thanks!

Answer 2 · 2017-06-26T08:09:12.000Z

I'm migrating Electron's website away from ruby and Jekyll to a node server, and gray-matter has become an instrumental piece of that transition

I forgot to mention... that's awesome!!! thanks!

Answer 3 · 2017-06-26T21:14:11.000Z

I found excerpt-html and gave it a try, but hit a snag: martinheidegger/excerpt-html#4

Answer 4 · 2017-06-26T21:39:17.000Z

I was looking at how it works in jekyll, and I believe we just need to get the block in the following example that says This is an excerpt, correct? Meaning anything between the front-matter and the next ---.

---
foo: bar
---
This is an excerpt.
---
This is content.

Answer 5 · 2017-06-26T21:47:36.000Z

Snag 2: martinheidegger/excerpt-html#5

Answer 6 · 2017-06-26T21:48:22.000Z

Meaning anything between the front-matter and the next ---.

Yes, assuming --- is configured as the excerpt_separator in Jekyll's config.yml file. The default is to grab the first paragraph.

Answer 7 · 2017-06-26T21:56:31.000Z

Is it an option to have gray-matter only extract the excerpt when --- is defined? It seems like that is most relevant to this lib, since front-matter is used with more than HTML, and users would be able to use excerpt-html or whatever is better suited to the language used in the file (markdown, html, plain text, latex, etc).

If we start parsing HTML etc, then we either would need to create logic/code around detecting content type, or we'll need to know the type of file that was passed. Currently, gray-matter just takes a string.

Answer 8 · 2017-06-26T21:59:10.000Z

Yeah tricky. Maybe this is too convoluted?

It might be better to just use gray-matter as-is, then fetch excerpts in our own custom way..

Answer 9 · 2017-06-26T22:01:50.000Z

well, we can enable excerpts with this code right before returning the file:

  if (opts.excerpt === true) {
    var idx = file.content.indexOf('\n---');
    if (idx !== -1) {
      file.excerpt = file.content.slice(0, idx);
      file.content = file.content.slice(idx + 4);
    }
  }

This should work pretty consistently. Seems like a neat idea IMHO.

Answer 10 · 2017-06-26T22:09:38.000Z

I'm heading out for the evening, but I'll check back in the morning. have a good evening

Answer 11 · 2017-06-26T22:10:26.000Z

That little snippet looks good, but the content should include the excerpt.

Answer 12 · 2017-06-26T22:10:37.000Z

Have a good night! To be continued...

Answer 13 · 2017-06-27T10:06:12.000Z

That little snippet looks good, but the content should include the excerpt.

Got it! Do we remove the ---? Or does that stay as well?

Answer 14 · 2017-06-27T14:59:54.000Z

Oh I see, I just read more in the Jekyll docs and it's possible to pass in an excerpt_separator. That's easy, we can do that too.

It also appears that if a separator is not used, Jekyll doesn't even look for an excerpt. Still reading up.

edit: okay after reading more, checking issues and talking it over with a colleague, I guess the rule in Jekyll is to only extract excerpts from "posts", but not "pages". I'm assuming that this is because posts are more likely to have content, and that content is most likely in markdown or a similar non-markup/plain text language. However, I believe Jekyll still tries to extract an excerpt even if an excerpt_separator is not defined. Which is what (I believe) you are trying to solve?

My suggested approach would be for us to do something similar:

allow an excerpt_separator to be defined on options or front-matter (file.data)
if no separator is defined, don't do anything
if options.excerpt is a function, we can call that to extract the excerpt

how does that sound?

cc @doowb

Answer 15 · 2017-06-27T17:11:47.000Z

how does that sound?

👍

Answer 16 · 2017-06-28T14:42:16.000Z

on it, I'll try to push up my changes today

Answer 17 · 2017-06-30T09:12:20.000Z

took me a little longer than expected. as usual, docs took the longest lol. I've been meaning to make other improvements for a while, so I took care of those as well. But for the vast majority of users there shouldn't be any breaking changes. please let me know if you have any issues.

Answer 18 · 2017-06-30T21:51:25.000Z

Thank you, @jonschlinkert. Great followthrough. 🙏

Answer 19 · 2017-07-01T00:06:21.000Z

np, please let me know if the implementation differs from what you expect. I'll get it sorted out.