Technical Stuff

Things you probably don't need to know unless you have a problem.

Have a question?

If you're not happy with the docs, you can browse the source code or submit an issue. Better yet, do both! & send a PR :D <3

Writing a literal @import inside markdown

If you don't want an import to be done. You just want to write @import
You'll need a zero-width-non-joiner between the @ sign and import. You can copy+paste this: @‍import(ExampleOfImportKey) or do an internet

deleteExistingDocs

Existing docs can only be deleted if they pass the sanity checks, as follows:

<?php  
if (!$dryRun&amp;&amp;$this-&gt;configs['deleteExistingDocs'][0]===true){  
    $root = $this-&gt;rootDir;  
    $root = realpath($root);  
    $docsDir = $this-&gt;rootDir.'/'.$this-&gt;configs['dir.docs'][0];  
    $docsDir = realpath($docsDir);  
          
    // To avoid removing things like /home/user/ and /var/www/ or shorter paths  
    // My assumption for shortest path is: /home/user/asubdir/projectdirs  
    // Projects COULD be at /home/user/projectdir, but mine likely never will be... &amp; I think that seems silly.  
    // I expect Windows to have even longer base paths?  
    $rootSlashArray = explode('/', str_replace('\\', '/', $root));  
    $docSlashArray = explode('/', str_replace('\\','/', $docsDir));  
    if (strlen($docsDir)&gt;strlen($root)  
        &amp;&amp; $root!=''  
        &amp;&amp; count($rootSlashArray)&gt;3  
        &amp;&amp; count($docSlashArray) &gt; count($rootSlashArray)  
        &amp;&amp; strpos($docsDir, $root)===0  
    ) {  
        \Tlf\Scrawl\Utility::DANGEROUS_removeNonEmptyDirectory($docsDir);  
    }  
}  

Default Configs

Default Configs are as follows:

• dir.docs: docs or doc or doc
• dir.template: docs-src or doc-src or docs-src
• dir.code: src or code or src
• file.conf: .config/scrawl.json or .scrawl.json or .config/scrawl.json
• file.code.ext: *
• file.template.ext: .src.md
• deleteExistingDocs: false
• markdown.preserveNewLines: true
• markdown.prependGenNotice: true
• scrawl.ext: []
• readme.copyFromDocs: true
• ext.PhpApiScraper: true

The actual code for deriving these defaults is:

<?php  
protected function inferDefaultOptions(){  
    $defaults = [];  
    $src = $this->pwd;  
  
    if (is_dir($src.'/docs'))$defaults['dir.docs'] = 'docs';  
    else if (is_dir($src.'/doc'))$defaults['dir.docs'] = 'doc';  
    else $defaults['dir.docs'] = 'doc';  
  
    if (is_dir($src.'/docs-src'))$defaults['dir.template'] = 'docs-src';  
    else if (is_dir($src.'/doc-src'))$defaults['dir.template'] = 'doc-src';  
    else $defaults['dir.template'] = 'docs-src';  
  
    if (is_dir($src.'/src'))$defaults['dir.code'] = 'src';  
    else if (is_dir($src.'/code'))$defaults['dir.code'] = 'code';  
    else $defaults['dir.code'] = 'src';  
  
    if (is_file($src.'/.config/scrawl.json')){  
        $defaults['file.conf'] = '.config/scrawl.json';  
    } else if (is_file($src.'/.scrawl.json')){  
        $defaults['file.conf'] = '.scrawl.json';  
    } else {  
        $defaults['file.conf'] = '.config/scrawl.json';  
    }  
  
    $defaults['file.code.ext'] = '*';  
  
    $defaults['file.template.ext'] = '.src.md';  
  
    $defaults['deleteExistingDocs'] = false;  
  
    $defaults['markdown.preserveNewLines'] = true;  
    $defaults['markdown.prependGenNotice'] = true;  
  
    $defaults['scrawl.ext'] = [];  
  
    $defaults['autoload'] = ['classmap'=>[]];  
  
    $defaults['readme.copyFromDocs'] = true;  
  
    $defaults['ext.PhpApiScraper'] = true;  
  
    return $defaults;  
}