Taeluf.com

Markdown Verbs

Markdown Verbs are essentially just functions you can write in your .src.md files. (I'm not sure why I call them verbs, but I do)

Also see: Templates, AST Templates

Docs

  • Calling Markdown Verbs
  • Create Markown Verbs
  • Built-in verbs
  • Import/Export

Calling Markdown Verbs

This must be in a .src.md file in your configured dir.src.

Syntax:

@verb_name(arg1, arg2)

Notes:

  • The output of the @function_call() will replace the @function_call()
  • Arguments cannot contain commas (,) or closing parenthesis ())
  • Place a backslash (\) after the @ sign to prevent the function from being called, like @\see(some_file). (Alternatively, place a zero width non-joiner after the @, but then people won't know it's there when they copy+paste your example.)
  • If a verb (function) does not exist, then the function call will remain, unchanged

Create Markdown Verbs

  1. Create a bootstrap file (Configured via file.bootstrap)
    • or implement the bootstrap() method in your extension
  2. Call $scrawl->add_md_verb('verb_name', $callable) (use $this->add_md_verb() in your bootsrap file)
  3. Implement the callable: function($arg1, $arg2){ echo "Anything"; }

Now calls to @verb_name(arg1, arg2) will be replaced with "Anything" (the output of your callable)

Built-in verbs

Available Verbs: import(), file(), template(), link(), easy_link(), hard_link(), see_files(), see(), system(), claim(), ast()

  • @import(): Import something previously exported with @export or @export_start/@export_end
    • Usage: @import(Namespace.Key)
    • Output: whatever was exported by @export(key) or @export_start(key) to @export_end(key)
  • @file(): Copy a file's content into your markdown.
    • Usage: @file(rel/path/to/file.ext)
    • Output: the file's content, trimmed.
  • @template(): Load a built-in template or a template from a configured template directory.
    • Usage: @template(template_name, arg1, arg2) the args are passed to the template as an array
    • Output: the string output of the executed .md.php file.
  • @link(): Output links configured in your scrawl.json config file, under the "links" key. Config format is {..., "links": { "link_name": "https://example.org"} }
    • Usage: @link(link_name)
    • Output: [LinkName](https://url.com)
  • @easy_link(): Get a link to common services (twitter, gitlab, github, facebook)
    • Usage: @easy_link(twitter, TaelufDev)
    • Output: [TaelufDef](https://twitter.com/TaelufDev)
  • @hard_link(): Returns a markdown link. (May provide validation in the future)
    • Usage: @hard_link(https://example.com, Optional Name)
    • Output: [Optional Name](https://example.com)
  • @see_files(): Outputs multiple markdown links.
    • Usage: @see_files(/rel/path1.md; Name1, /rel/path2.md; Name2, ...) names are optional.
    • Output: [Name1](/rel/path1.md), [Name2](/rel/path2.md)
  • @see(): Get a link to a file in your repo
    • Usage: @see_file(rel/path.ext, Optional Name)
    • Output: [Optional Name](rel/path.ext) or [rel/path.ext](rel/path.ext) if no name provided
  • @system(): Run a system command: @system(system_command, ...options). Options can be trim, trim_empty_lines, last_x_lines, int
    • Usage: @system(bin/something), @system(bin/something, trim), @system(bin/something, last_x_lines, 5)
    • Output: the output of the system_command, modified by the provided options.
  • @claim(): Verify that a specific test is passing, outputting a pass/fail string, and linking to its file & line number. (REQUIRES taeluf/tester, and does not have an integration with PHPUnit.)
    • Usage: @claim(TestName) - All tests prefix with test. Do NOT include test in the name.
    • Output: The configured claim.pass or claim.fail string and a relative link to the test (tested working on GitLab & GitHub)
  • @ast(): Print information about a parsed PHP class. Use template ast/debug to get information about the AST path. (Note: The templates are not very good, but you can create your own)
    • Usage: @ast(ast_path, template_name, filters), like @ast(class[ClassName].methods[MethodName].docblock[Description], ast/default, filter1.filter2.filter3). See available filters & templates
    • Output: the template's string output or the value pointed to by the ast_path if a template is not used and the value is a string.

Note: @ast() can accept a dot-path like class.ClassName.methods.MethodName, but the array-access version is recommended.

Import/Export

There are two ways to export, and either export can be printed in a markdown file via:

\@import(Key)

@export(Key)

@export(Key) exports all text in a docblock above the @export(). Each line of the export is trimmed and the asterisks (*) are removed.

Example:

<?php  
  
/**  
* Get an array of books with the partial title matching  
*  
* @param $like_title string  
* @return array of Book objects  
* @export(get_books)  
*/  
function get_books(string $like_title): array{}

Then you could \@import(get_books) in your documentation.

@export_start(Key) & @export_end(Key)

Use this to export all text between the two export tags.

Example (from liaison's tests):

<?php  
  
$lia = new \Lia();  
$package = new \Lia\Package($lia, 'test');  
new \Lia\Addon\Resources($package);  
  
// @export_start(ResourcesAddon.AddResources)  
$resources = \Lia\Addon\Resources::from($lia); // your Liaison instance  
  
// Files will be concatenated and added to a singular css file  
$private_dir = dirname(__DIR__,2).'/input/private/resources/';  
$resources->addFile($private_dir.'/undeliverable-styles.css');  
$resources->addFile($private_dir.'/undeliverable-scripts.js');  
  
// URLs will be added as `<link>` and `<script>` tags and added to the HTML head  
$resources->addURL('/resources/page-layout.css'); // deliverable on your site  
$resources->addURL('https://cdn.example.com/my-namespace/dancing-bear.js'); // external file  
// @export_end(ResourcesAddon.AddResources)

Then Liaison documentation uses \@import(ResourcesAddon.AddResources) in its documentation to print the above code.