API documentation

[kescobo]

As noted on slack, I've run into a couple of road-blocks when exploring some features. Noting them here for posterity:

• on this page, there's an example block with {{ispage blog/*}} {{insert head_blog}}{{end}}. ispage has some documentation here, but I can't find where insert is documented.
• Similarly, things like {{fill x}} here aren't super clear, but I can't find other documentation.
• Separately, I found the function in the julialang.org utils.jl file to generate blogposts, and they use the pagevar function, which I can't find on the docs page, but which does have a docstring from the REPL

To quote tlienart:

Thanks, feel free to list these points in an issue, so we can chip at it gradually :slightly_smiling_face: Just quickly in case this is blocking you now:

• insert inserts anything "as is" in HTML taking as base path the _layout/ folder
• fill inserts the content of a page variable, shortcut {{x}} is the same as {{fill x}} if x is un-ambiguous (i.e. there is no hfun_x )
• pagevar is to get a page variable from a page that is different from the current one it works as pagevar(rpath, name) where rpath is the path of the other page like blog/foo/bar.md and name is the name of the page variable defined there that you'd want to include.

[kescobo]

Honestly, I think having a page for the docstrings of package functions that currently have them would go a long way. The insert / fill distinction might not be captured there, of course, but I think that would help me a lot.

[tlienart]

Thanks, these are all reasonable requests :-)

[kescobo]

To add to this - there's actually a bunch of additional documentation in the template repos that's not at franklinjl.org. For example, there doesn't seem to be any mention of hfun_ in the main site, but there's good explanations in the template repos.

[tlienart]

https://franklinjl.org/syntax/utils/

[kescobo]

Oh weird -

I guess that's the obvious place to look in the site tree.

[tlienart]

hmm yeah that's annoying, try again with hfun_ and it works... 🙄 this is something I should try to figure out with lunr.