[Feature] Improved post excerpts / previews

[adam-zethraeus]

(This issue is primarily intended to spark conversation and gauge interest!)

Most themes i've seen use {{excerpt}} for post snippets. Some use {{content words="#"}} or {{contents characters="#"}}. All of these options are lackluster as they remove context or content, and offer no control of the process.

An improved API would be awesome. I see two primary options:

1. Preview annotation
2. Context sensitive {{content}} blocks

Preview annotation could be or some nicer syntax to wrap or designate the end of the text to be shown in the preview. It could perhaps even allow for content separate from that shown in the actual post. The preview could be made available to themes with an API like {{preview}}. This could be good for writers who want to carefully craft their preview blocks. (This functionality sounds like it might be great for developing as plugin, at least initially.)

Context sensitivity in {{content}} (and {{excerpt}}) blocks is more interesting. It could make sense as default functionality, serving initially to just do better than chop text mid-sentence. Ghost could provide an API like {{content max-words="#"}} and attempt to more intelligently do sub-contenting within requested bounds.
To some extent, this could perhaps be offloaded to the Downsize script that Ghost is currently using (and I'm going to look into it!), but Downsize's job is to take arbitrary html and return shortened html and in working within that bound it both loses contextual hints from markdown, and is forced not to make assumptions that would be solid for Ghost. (For example, that the input is HTML that can be generated by markdown).
Perhaps snippeting could be done better in markdown itself? That obviously has a whole host of problems though!

[kezzbracey]

Hey zethraeus,

I really like your thinking. I just opened up a topic similar to this, which Hannah asked me to bring in here for some focus. I'll add that in below.

Before I do though I just want to say I think you have a really good point about writers wanting to carefully craft previews.

Do you see this is something that is filtered out of the post via a notation marking the beginning and end of such a preview, so a writer could have the option of an excerpt not being out of the content in the post itself?

From other topic:

I was just thinking, given we don't have a "more" tag insertion function, and people often have quite different preferences on how they want to show content on their homepage & archives (i.e. length, stripping html or not), would this work?

Both the "excerpt" and "content" helpers accept "words" and "characters" as options. The difference between the two helpers is that one strips html and the other doesn't.

So what if instead of having the "excerpt" helper, we had "strip_html" as an option for the "content" helper?

The functions of the two helpers could then be combined into one, with the processing method and returned value depending on the "strip_html" setting, and it could be used in a theme like:

{{content characters / words="100" strip_html="true / false"}}

(The "strip_html" property would default to false. If "strip_html" were true and no characters / words option were set it could still default to 50 words).

If we did this, perhaps that would also lay the ground work for a UI setting to allow users to control each of these values.

So perhaps under the current "Posts per page" setting there could also be something like:

• Post archive previews, trim to: xxxxxx (text field) words / characters (radio button)
• Post archive previews, strip HTML: Yes / No (radio button)

The defaults on these settings could be determined by the theme, but the helper could look to see if the user had set anything in these fields, and if so override the output with those saved settings.

Could this perhaps be a relatively neat and simple way to give users some control over these display settings?

I may be missing something that's planned for the future advanced excerpts in line for 0.8, but if not, what do you think?

I'm still something of a beginner, but looking at the current helper functions I think I'd be up for taking a run at combining them if the idea has any merit.

[adam-zethraeus]

I like the idea of combining the helpers, as long as we can't anticipate settings where you might have parameters that matter to one and not the other.

[adam-zethraeus]

As far as user tweaking of the settings perhaps the (currently hypothetical) theme admin panel should take care of this?

[kezzbracey]

I do think the idea needs some more thinking through, like perhaps doing a practical trial of the combined function while developing a few themes to see if it has any shortcomings.

Its validity would also depend on if there are things I'm not aware of planned for excerpts in the future.

As for theme admin panels, I wasn't thinking of adding new options to the degree a extra panel would be needed. I was only thinking along the lines of one or two extra settings that might fit in admin in the same context as does the current logo, cover, posts per page types of settings.

There's a fine line between what should be an admin setting and what should be done within the theme itself. Even though a couple of new UI settings is my suggestion, if I'm honest I'd actually still rather err on the side of too few rather than too many.

[adam-zethraeus]

Its validity would also depend on if there are things I'm not aware of planned for excerpts in the future.

Hopefully @ErisDS can chime in a bit here, but i get the impression that there's space for community design work.

Even though a couple of new UI settings is my suggestion, if I'm honest I'd actually still rather err on the side of too few rather than too many.

Yeah, user-facing setting overload would suck.

[ErisDS]

Settings overload is something we're very wary of. In terms of future plans for the excerpt, I think @zethraeus has touched on all of them:

• making it possible to limit by paragraph
• making it possible to do some sort of custom version via a convention such as <!-- more --> in the editor

The only additional ones might be:

• making it possible to change the excerpt via an app.

In my opinion excerpts and content are distinct concepts and need to have different helpers, but I'm willing to be shown I'm wrong :)

[runar]

Regarding the helpers: I agree with @ErisDS that excerpts and content are distinct concepts and should be treated that way. The difference becomes clearer if we take away the arguments: {{content}} should print the whole post/page content, while {{excerpt}} should default to the first X characters/words/paragraphs. I’m not sure about stripping all HTML from the excerpt, though.

[kezzbracey]

I had a good chat with @halfdan about this and he had what I thought was a good idea for handling post intros that would avoid needing to filter content to look for a 'more' tag.

He suggested, as you mentioned above @ErisDS, using an app to handle it and having a UI element in a collapsible sidebar section where you could compose your custom index/tag archive intro.

That way you would avoid adding anything too intrusive to the layout, given it's so nice to use as it is now, and you could also avoid doing anything inline. You'd also get full control over exactly what was in your intro, and you could use a section like this to handle addition of a featured/cover intro or video that the {{content words="0"}} approach is being used for in themes now.

In this context, the advantage of rolling the {{excerpt}} and {{content}} functions in together would be that an app that handled this process could then target a single function. It wouldn't have to factor in consideration of which of the two tags a theme was using.

I do see how conceptually {{excerpt}} and {{content}} are different, and I'm not necessarily arguing for rolling them in together or not as I'm still not sure which seems to be most advantageous.

However the consideration I'm wondering about is whether it might be easier for a theme developer to use something like {{content text_only="true" words="50"}}, hence standardizing the function that is always used, than it might be for a plugin developer to have to check which function is used for apps that target index/tag posts.

What do you all think about that aspect of things?

[Lerg]

Hello,

I was able to implement the <!--preview--> feature on my own.

I have described it in enough details in my blog
http://spiralcodestudio.com/manual-post-cut-for-ghost/

Source code included
https://gist.github.com/Lerg/fc2c412d59347c870aa1

You can see how it works if you open the main page of my site and see three dots at the bottom of that post.
http://spiralcodestudio.com/

I don't know if it's good enough to be included in the core, but I am very happy with this implementation.

[ErisDS]

Closing this in favour of #4017