I'm trying to build a site with Hugo and having a hard time understanding some of their documentation. Specifically, when displaying frontmatter in a template.
There are functions you can preform on variables inside the handle bars. ex: {{ range .Data.Pages }} What is range? I can't find any documentation on what these functions do. Or is it just plain Go code and anything Go is fair game? Just looking for documentation so I can figure out what I need.
These are functions that have specifically been made available to Go templates (you can't just use any Go functions). They include the built-in functions documented in the golang.org template docs which JimB linked to in his comment, and also Hugo-specific functions which are documented on the Hugo template functions page.
Related
I want to search in the go pkg go-git.
ctrl+shift+f searches only in my module.
Probably this will not directly answer, but it's an workaround, that I personally prefer:
Hovering over a function, that is from a foreign package, VS Code shows the godoc description. There is always a link to pkg.go.dev (This link is for the PlainClone example):
Following it you are redirected directly to GO's package website.
Here is already a nice list with the module's functions.
if you want to dive deeper:
On the top of the repository there is the link to the repo host.
Experiences show, that this is mostly Github. While GitHub's search used to be proscribed, it can nowadays be a mightful tool:
https://docs.github.com/en/search-github/searching-on-github/searching-code#search-within-a-users-or-organizations-repositories
Again I mention that is very subjective, but GO's complex way of storing modules locally with it's many env variables and stuff made me feel using the internet is more comfortable =)
Because of the complexity of the existing webpage templates, I am trying to develop my own template engine with both easier syntax and the function I need.
When implementing the function of "include an other template", I began to wondering how to manage the variables in the included template, and those in the template included deeper.
It seems that adding some prefix to manage the namespace is to solve the problem, but I think it makes the variable names too long.
So how can I manage them in a good and simpler way?
I'm using a slightly modified version of the example generator from Jekyll's plugins section of their docs (https://github.com/mojombo/jekyll/wiki/Plugins#generators) and I'm curious if there is any way to parse a liquid/markdown file instead of a plain HTML files from the example?
Notice this line:
self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
That category index.html file is the target file which will be used in generated files. My goal is to be able to pass an object to a my generator from my _config file which I can then use to build a bunch of pages from a .markdown file instead. Does anyone know if this is possible or have any recommendations for achieving this? I looked into the Kramdown lib that's used to parse markdown internally, and I'm not opposed to invoking it myself if I have to, just wasn't sure if I was going deeper than I needed to for something that should be so simple. The API for the Page object which my generator creates is here: http://ruby-doc.org/gems/docs/j/jekyll-0.12.0/Jekyll/Page.html
Thanks a ton,
- Keith
You can generate virtually any format you want, from virtually any data source you want, in a generator, because you're writing straight Ruby with full access to the Jekyll object model. For example, here's a generator I put together the other night that fetches GitHub commits during jekyll build.
The question I would be asking is this:
Do I need a plugin to accomplish this?
If so, do I need a formal generator plugin as discussed in the Jekyll docs?
Or should I subclass, monkey-patch, or otherwise change the behavior of the built-in generator?
Also, the differences between Markdown and HTML files in this context (where you control 100% of what gets generated) are mostly nominal. read_yaml IIRC will actually read the front matter from both, so that shouldn't be an issue.
I've seen it before, but I can't remember which project or which documentor they used (if any).
I'm pretty sure it was a JS project, probably a Node.JS module.
Anyhow, the documentation was listed by file, and each page displayed as 2 columns, one with the inline documentation, and the other with the code.
Does anyone know which tools allow for this?
"Annotated Documentation" is what I was trying to think of!
The tool was docco.
The above link is docco's documentation as documented using docco.
Ruby has a few good document generators like Yard, rDoc, even Glyph. The thing is that Sphinx does websites, PDF's, epub, LaTex...etc. It does all these things in restructuredtext.
Is there an alternative to this in the Ruby world? Maybe a combination of programs? If I could use Markdown as well that would be even better.
Since version 1.0, Sphinx has had a concept of "domains" which are ways of marking up code entities (like method calls, objects, functions, whatever) from lannguages other than Python and/or C.
There is a ruby domain, so you could just use Sphinx itself. The only thing you would be missing (I think) is Sphinx's ability to create documentation from source automatically using the autodoc extension, which works specifically on Python code.
If you want to use Markdown, you might check out JDoc, which is a very simple, Ruby-based documentation framework that lets you use widely-supported markup and put it under source control. It lets you edit the documentation in your text editor of choice, and it supports:
Markdown or Textile
syntax highlighting
easy internal links
a hierarchical documentation structure (useful for large projects)
customizable styling and structure (but it looks nice out of the box, too)
It generates static HTML, so the resulting documentation is easy to host and doesn't have much of an impact on your server load.
To see it in action, check out wpmvc.org.
Another couple of options would be to use Middleman which is a static site generator that accepts either Kramdown or Markdown as input.
There are also frameworks that are designed specifically for technical documentation that use Middleman (both of which are on GitHub) including lord/slate and pnerger/dpslate (the later is a fork of the former and provides some enhancements that were not appropriate for pulling). The Slate format provides a format for documentation that includes many of the features of Sphinx with some additional enhancements. It features a three-pane view of a document which includes an automatically generated Table of Contents, a Main center body, and then sample code panel to the right. Like Sphinx the sample code has syntax highlighting.