Documentation Improvements: Variables/Helpers

[derikb]

Check List

Please check followings before submitting a new feature request.

• I have already read Docs page
• I have already searched existing issues

Feature Request

New to Hexo and finding some inadequacies in some of the documentation.

• Under Helpers List Tags (and other list_ helpers) the "style" option doesn't offer what one can use if one doesn't want the default "list". What other options are there?
• Under Variables a few of the variables are just listed as type "???" or "array of ???", including
  • The page.next and page.prev vars (which seem to return some kind of page/post object, but I'm not totally clear the limits of what properties it has.
  • The page.tags and page.categories return some kind of object, but I can't find any documentation about what vars those objects might have.

[derikb]

Ok, looks like the alternative value in the list_ helpers for "style" is false.

[tcrowe]

Hey @derikb 👋

One option for advanced users and theme makers is to use those variables directly.

These will be the variables available by default:
https://hexo.io/docs/front-matter#Settings-amp-Their-Default-Values
https://hexo.io/docs/variables#Page-Variables

In the front matter at the top you can create your own too:

title: one two three
tags:
  - four
  - five
  - six
customThing: seven

In the template it should be available as page.tags or post.tags, depending on the context. If you want to get at customThing it would be like page.customThing or post.customThing.

Default use:
https://github.com/hexojs/hexo-theme-landscape/blob/master/layout/_partial/post/tag.ejs#L2

site.tags also:
https://github.com/theme-next/hexo-theme-next/blob/999f0f786f06f63493d117e413c8e7724bc66d80/layout/_partials/sidebar/site-overview.swig#L59

---

So, if you know how to edit the templates you can access and loop through each of these things.

The database it's using is called warehouse. It has a lot of nifty queries it can do. If you start using that in your theme and want some help just ping us back!

---

Was any of that of help?

[derikb]

Not really... @tcrowe but thanks for responding...

Does looping through post.tags just get me an array of strings? Was kind of hoping it gave me some other data (like the archive url for that tag, etc.)? (I wanted to further customize what list_tags() gives me by directly accessing the tag data, but I'm not clear what is in that data.

And post.next and post.prev... are they objects that have all the same vars I would have if I were in the template/layout for the individual post? If so, that would be a good thing to have in the docs to clarify that.

[tcrowe]

If you jump into your templates in ./theme/your-theme/... you can start outputting the data and you can see what's in it. It just takes a little time and effort.

[noraj]

@derikb I have made various PR on list_tags in 2020, look now there are plenty new options and the doc was updated.