Learn how to use Trifle::Docs DSL.
Usage
Trifle::Docs
comes with a couple module level methods that are shorthands for operations.
Each of these methods accepts optional custom configuration. If no configuration has been passed in, it defaults to global configuration.
sitemap(**options)
options
- hash of optional arguments:config
- optional configuration instance ofTrifle::Docs::Configuration
. It defaults to global configuration, otherwise uses passed in configuration.
Returns a full tree structure of your folders. Each item includes metadata for a specific file. You can use this to generate menus or one of those sitemaps that noone uses.
Example sitemap for Trifle documentation including only blog and _meta. To cut down too much content it uses slice
to cut down unnecessary sitemap branches and include only blog
branch.
irb(main):002:0> Trifle::Docs.sitemap.slice('blog', '_meta')
=> {"blog"=>{"2022-07-introduction"=>{"_meta"=>{"title"=>"Introduction to Trifle Blog", "date"=>"2022-07-12 18:16:31", "author"=>"Jozef Vaclavik", "template"=>"blog", "url"=>"/blog/2022-07-introduction", "breadcrumbs"=>["blog", "2022-07-introduction"]}}, "_meta"=>{"title"=>"Blog", "nav_order"=>1, "template"=>"blogs", "url"=>"/blog", "breadcrumbs"=>["blog"]}}, "_meta"=>{"title"=>"Home", "url"=>"/", "breadcrumbs"=>[]}}
_meta
- holds the metadata about each part of tree.
content(url: String, **options)
url
- string representation of the URL.options
- hash of optional arguments:config
- optional configuration instance ofTrifle::Docs::Configuration
. It defaults to global configuration, otherwise uses passed in configuration.
Returns a HTML content of the file that can be used in a template.
Example content for first blog post you can find here.
irb(main):003:0> Trifle::Docs.content(url: 'blog/2022-07-introduction')
=> "<h1 id=\"welcome-to-trifle-blog\">Welcome to Trifle Blog</h1>\n\n<p>On this place you will find announcements worth announcing and other interesting <em>things</em> that occured. For example major versions, milestones and improvements. I would not hold my breath for regular updates. These are after all super-simple plugins.</p>\n\n<p>Anyways; welcome and come again!</p>\n"
meta(url: String, **options)
url
- string representation of the URL.options
- hash of optional arguments:config
- optional configuration instance ofTrifle::Docs::Configuration
. It defaults to global configuration, otherwise
Returns a metadata of the file. This may include title
, template
, nav_order
or others.
Example metadata for first blog post you can find here.
irb(main):004:0> Trifle::Docs.meta(url: 'blog/2022-07-introduction')
=> {"title"=>"Introduction to Trifle Blog", "date"=>"2022-07-12 18:16:31", "author"=>"Jozef Vaclavik", "template"=>"blog", "url"=>"/blog/2022-07-introduction", "breadcrumbs"=>["blog", "2022-07-introduction"], "toc"=>"<ul>\n<li>\n<a href=\"#welcome-to-trifle-blog\">Welcome to Trifle Blog</a>\n</li>\n</ul>\n"}
collection(url: String, **options)
url
- string representation of the URL.options
- hash of optional arguments:config
- optional configuration instance ofTrifle::Docs::Configuration
. It defaults to global configuration, otherwise
Returns a single branch of a sitemap tree for specific url
. This can be useful when redering list of nested items. For example blog posts. Instead of navigating through .sitemap
to specific branch, you can use .collection
with url
to get the list.
Example of collection of blog posts under blog
url.
irb(main):005:0> Trifle::Docs.collection(url: 'blog')
=> {"2022-07-introduction"=>{"_meta"=>{"title"=>"Introduction to Trifle Blog", "date"=>"2022-07-12 18:16:31", "author"=>"Jozef Vaclavik", "template"=>"blog", "url"=>"/blog/2022-07-introduction", "breadcrumbs"=>["blog", "2022-07-introduction"]}}, "_meta"=>{"title"=>"Blog", "nav_order"=>1, "template"=>"blogs", "url"=>"/blog", "breadcrumbs"=>["blog"]}}
_meta
- holds the metadata about each part of tree.
Thats really all there is. You can use these methods directly and integrate it in views, or you can use build in Sinatra app.