Added new macro (MacroInlineFileLink) to link external files to docum…

…entations output directory

README.md

@@ -10,7 +10,7 @@ ublaboo/anabelle
 
 ## Api documentation generator (JSON-RPC / REST)
 
-(No matter whether you're using REST or JSON-RPC)
+(No matter whether you're using REST or JSON-RPC or some other api architecture/scheme)
 
 ### Example
 
@@ -76,6 +76,15 @@ Method section definition. This macro available only in `index.md` file.
 @@ user.confirm-registration:methods/user.confirm-registration.md
 ```
 
+#### `[File link](foo/bar/data.json)`
+
+[File link](foo/bar/data.json) will create a link to file (`foo/bar/data.json`). The file will be copied to documentation output directory for safety reasons.
+
+```md
+[File link](foo/bar/data.json)
+[Project root directory file link](../app/schema/user.json)
+```
+
 
 ## How to use anabelle
 

docs-src/about.md

@@ -1,3 +1,5 @@
 ## About
 
 Blah blah blah about
+
+[This](../assets/favicon.ico) is a link to a file (`assets/favicon.ico`) that will be copied do documentations directory. It can be used for example for linking project-related json files, config YAML files and other important data.

docs/about.html

@@ -1 +1 @@
-<h2>About</h2> <p>Blah blah blah about</p>
+<h2>About</h2> <p>Blah blah blah about</p> <p><a href="assets/favicon.ico" target="_blank">This</a> is a link to a file (<code>assets/favicon.ico</code>) that will be copied do documentations directory. It can be used for example for linking project-related json files, config YAML files and other important data.</p>

src/Markdown/Macros/MacroInlineFileLink.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ublaboo\Anabelle\Markdown\Macros;
+
+use Nette\Utils\Html;
+use Ublaboo\Anabelle\Generator\Exception\DocuGeneratorException;
+
+final class MacroInlineFileLink implements IMacro
+{
+
+	const LINK_PATTERN = '/\[((?:[^][]++|(?R))*+)\]\(([^\)]*)\)/um';
+
+
+	/**
+	 * @throws DocuGeneratorException
+	 */
+	public function runMacro(
+		string $inputDirectory,
+		string $outputDirectory,
+		string & $content // Intentionally &
+	): void
+	{
+		/**
+		 * Substitute "#include" macros with actual files
+		 */
+		$content = preg_replace_callback(
+			self::LINK_PATTERN,
+			function(array $input) use ($inputDirectory, $outputDirectory): string {
+				$text = $input[1];
+				$path = trim($input[2], '/');
+
+				if (file_exists($inputDirectory . '/' . $path)) {
+					$targetPath = str_replace(['../', './'], '', $outputDirectory . '/' . $path);
+
+					if (!file_exists(dirname($targetPath))) {
+						mkdir(dirname($targetPath), 0755, true);
+					}
+
+					copy($inputDirectory . '/' . $path, $targetPath);
+
+					$targetPath = preg_replace('~^[^/]+/~', '', $targetPath);
+
+					return (string) Html::el('a')->href($targetPath)
+						->setText($text)
+						->target('_blank');
+				}
+
+				return "[$text]($path)";
+			},
+			$content
+		);
+	}
+}

src/Markdown/Parser.php

@@ -14,6 +14,7 @@
 use Ublaboo\Anabelle\Markdown\Macros\MacroBlockVariableOutput;
 use Ublaboo\Anabelle\Markdown\Macros\MacroCleanIndex;
 use Ublaboo\Anabelle\Markdown\Macros\MacroInclude;
+use Ublaboo\Anabelle\Markdown\Macros\MacroInlineFileLink;
 use Ublaboo\Anabelle\Markdown\Macros\MacroInlineVariable;
 use Ublaboo\Anabelle\Markdown\Macros\MacroInlineVariableOutput;
 use Ublaboo\Anabelle\Markdown\Macros\MacroSection;
@@ -120,6 +121,7 @@ private function setupMacros(): void
 		$this->macros[] = new MacroInclude;
 		$this->macros[] = new MacroInlineVariable($this->docuScope);
 		$this->macros[] = new MacroInlineVariableOutput($this->docuScope);
+		$this->macros[] = new MacroInlineFileLink($this->docuScope);
 		$this->macros[] = new MacroBlockVariable($this->docuScope);
 		$this->macros[] = new MacroBlockVariableOutput($this->docuScope);