457 lines
48 KiB
HTML
457 lines
48 KiB
HTML
|
<!DOCTYPE html><html><head>
|
||
|
|
<title>CLI_TUTORIAL</title>
|
||
|
|
<meta charset="utf-8">
|
||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
|
|
||
|
|
<link rel="stylesheet" href="file:///c:\Users\bernd.worsch\.vscode\extensions\shd101wyy.markdown-preview-enhanced-0.8.19\crossnote\dependencies\katex\katex.min.css">
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<style>
|
||
|
|
code[class*=language-],pre[class*=language-]{color:#333;background:0 0;font-family:Consolas,"Liberation Mono",Menlo,Courier,monospace;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;word-wrap:normal;line-height:1.4;-moz-tab-size:8;-o-tab-size:8;tab-size:8;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none}pre[class*=language-]{padding:.8em;overflow:auto;border-radius:3px;background:#f5f5f5}:not(pre)>code[class*=language-]{padding:.1em;border-radius:.3em;white-space:normal;background:#f5f5f5}.token.blockquote,.token.comment{color:#969896}.token.cdata{color:#183691}.token.doctype,.token.macro.property,.token.punctuation,.token.variable{color:#333}.token.builtin,.token.important,.token.keyword,.token.operator,.token.rule{color:#a71d5d}.token.attr-value,.token.regex,.token.string,.token.url{color:#183691}.token.atrule,.token.boolean,.token.code,.token.command,.token.constant,.token.entity,.token.number,.token.property,.token.symbol{color:#0086b3}.token.prolog,.token.selector,.token.tag{color:#63a35c}.token.attr-name,.token.class,.token.class-name,.token.function,.token.id,.token.namespace,.token.pseudo-class,.token.pseudo-element,.token.url-reference .token.variable{color:#795da3}.token.entity{cursor:help}.token.title,.token.title .token.punctuation{font-weight:700;color:#1d3e81}.token.list{color:#ed6a43}.token.inserted{background-color:#eaffea;color:#55a532}.token.deleted{background-color:#ffecec;color:#bd2c00}.token.bold{font-weight:700}.token.italic{font-style:italic}.language-json .token.property{color:#183691}.language-markup .token.tag .token.punctuation{color:#333}.language-css .token.function,code.language-css{color:#0086b3}.language-yaml .token.atrule{color:#63a35c}code.language-yaml{color:#183691}.language-ruby .token.function{color:#333}.language-markdown .token.url{color:#795da3}.language-makefile .token.symbol{color:#795da3}.language-makefile .token.variable{color:#183691}.language-makefile .token.builtin{color:#0086b3}.language-bash .token.keyword{color:#0086b3}pre[data-line]{position:relative;padding:1em 0 1em 3em}pre[data-line] .line-highlight-wrapper{position:absolute;top:0;left:0;background-color:transparent;display:block;width:100%}pre[data-line] .line-highlight{position:absolute;left:0;right:0;padding:inherit 0;margin-top:1em;background:hsla(24,20%,50%,.08);background:linear-gradient(to right,hsla(24,20%,50%,.1) 70%,hsla(24,20%,50%,0));pointer-events:none;line-height:inherit;white-space:pre}pre[data-line] .line-highlight:before,pre[data-line] .line-highlight[data-end]:after{content:attr(data-start);position:absolute;top:.4em;left:.6em;min-width:1em;padding:0 .5em;background-color:hsla(24,20%,50%,.4);color:#f4f1ef;font:bold 65%/1.5 sans-serif;text-align:center;vertical-align:.3em;border-radius:999px;text-shadow:none;box-shadow:0 1px #fff}pre[data-line] .line-highlight[data-end]:after{content:attr(data-end);top:auto;bottom:.4em}html body{font-family:'Helvetica Neue',Helvetica,'Segoe UI',Arial,freesans,sans-serif;font-size:16px;line-height:1.6;color:#333;background-color:#fff;overflow:initial;box-sizing:border-box;word-wrap:break-word}html body>:first-child{margin-top:0}html body h1,html body h2,html body h3,html body h4,html body h5,html body h6{line-height:1.2;margin-top:1em;margin-bottom:16px;color:#000}html body h1{font-size:2.25em;font-weight:300;padding-bottom:.3em}html body h2{font-size:1.75em;font-weight:400;padding-bottom:.3em}html body h3{font-size:1.5em;font-weight:500}html body h4{font-size:1.25em;font-weight:600}html body h5{font-size:1.1em;font-weight:600}html body h6{font-size:1em;font-weight:600}html body h1,html body h2,html body h3,html body h4,html body h5{font-weight:600}html body h5{font-size:1em}html body h6{color:#5c5c5c}html body strong{color:#000}html body del{color:#5c5c5c}html body a:not([href]){color:inherit;text-decoration:none}html body a{color:#08c;text-decoration:none}html body a:hover{color:#00a3f5;text-decoration:none}html body img{max-width:100%}html body>p{margin-top:0;margin-bottom:16px;word-wrap:break-word}html body>ol,html
|
||
|
|
/* Please visit the URL below for more information: */
|
||
|
|
/* https://shd101wyy.github.io/markdown-preview-enhanced/#/customize-css */
|
||
|
|
|
||
|
|
</style>
|
||
|
|
<!-- The content below will be included at the end of the <head> element. --><script type="text/javascript">
|
||
|
|
document.addEventListener("DOMContentLoaded", function () {
|
||
|
|
// your code here
|
||
|
|
});
|
||
|
|
</script></head><body for="html-export">
|
||
|
|
|
||
|
|
|
||
|
|
<div class="crossnote markdown-preview ">
|
||
|
|
|
||
|
|
<h1 id="markitect-cli-tutorial-clever-command-line-usage">MarkiTect CLI Tutorial: Clever Command-Line Usage </h1>
|
||
|
|
<h2 id="table-of-contents">Table of Contents </h2>
|
||
|
|
<ol>
|
||
|
|
<li><a href="#getting-started">Getting Started</a></li>
|
||
|
|
<li><a href="#core-workflow-patterns">Core Workflow Patterns</a></li>
|
||
|
|
<li><a href="#document-processing">Document Processing</a></li>
|
||
|
|
<li><a href="#template--schema-workflows">Template & Schema Workflows</a></li>
|
||
|
|
<li><a href="#data-analysis--querying">Data Analysis & Querying</a></li>
|
||
|
|
<li><a href="#advanced-techniques">Advanced Techniques</a></li>
|
||
|
|
<li><a href="#business-document-automation">Business Document Automation</a></li>
|
||
|
|
<li><a href="#troubleshooting--optimization">Troubleshooting & Optimization</a></li>
|
||
|
|
</ol>
|
||
|
|
<hr>
|
||
|
|
<h2 id="getting-started">Getting Started </h2>
|
||
|
|
<h3 id="installation--first-steps">Installation & First Steps </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Check MarkiTect is properly installed</span>
|
||
|
|
markitect <span class="token parameter variable">--help</span>
|
||
|
|
|
||
|
|
<span class="token comment"># View system statistics</span>
|
||
|
|
markitect stats
|
||
|
|
|
||
|
|
<span class="token comment"># Check database status</span>
|
||
|
|
markitect db-stats
|
||
|
|
</code></pre><h3 id="essential-setup-commands">Essential Setup Commands </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Initialize workspace - process your first document</span>
|
||
|
|
markitect ingest README.md
|
||
|
|
|
||
|
|
<span class="token comment"># List all processed files</span>
|
||
|
|
markitect list
|
||
|
|
|
||
|
|
<span class="token comment"># Check specific file status</span>
|
||
|
|
markitect stats README.md
|
||
|
|
</code></pre><hr>
|
||
|
|
<h2 id="core-workflow-patterns">Core Workflow Patterns </h2>
|
||
|
|
<h3 id="1-document-analysis-workflow">1. Document Analysis Workflow </h3>
|
||
|
|
<p><strong>Scenario</strong>: Analyze and understand a markdown document structure</p>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Step 1: Ingest the document</span>
|
||
|
|
markitect ingest document.md
|
||
|
|
|
||
|
|
<span class="token comment"># Step 2: View document metadata</span>
|
||
|
|
markitect metadata document.md
|
||
|
|
|
||
|
|
<span class="token comment"># Step 3: Check frontmatter</span>
|
||
|
|
markitect frontmatter-keys document.md
|
||
|
|
markitect frontmatter-get document.md title
|
||
|
|
|
||
|
|
<span class="token comment"># Step 4: Analyze AST structure</span>
|
||
|
|
markitect ast-show document.md <span class="token parameter variable">--format</span> tree
|
||
|
|
|
||
|
|
<span class="token comment"># Step 5: Generate schema from structure</span>
|
||
|
|
markitect schema-generate document.md <span class="token parameter variable">--output</span> document-schema.json
|
||
|
|
</code></pre><h3 id="2-content-extraction-workflow">2. Content Extraction Workflow </h3>
|
||
|
|
<p><strong>Scenario</strong>: Extract specific content types from documents</p>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Extract pure content (no frontmatter/tailmatter)</span>
|
||
|
|
markitect content-get document.md
|
||
|
|
|
||
|
|
<span class="token comment"># Get specific frontmatter values</span>
|
||
|
|
markitect frontmatter-get document.md author
|
||
|
|
markitect frontmatter-get document.md config.theme <span class="token comment"># nested values</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Extract contentmatter (MultiMarkdown key-value pairs)</span>
|
||
|
|
markitect contentmatter-keys document.md
|
||
|
|
markitect contentmatter-get document.md project_id
|
||
|
|
|
||
|
|
<span class="token comment"># Check tailmatter (QA checklists, metadata)</span>
|
||
|
|
markitect tailmatter-keys document.md
|
||
|
|
markitect tailmatter-get document.md qa.reviewed
|
||
|
|
</code></pre><h3 id="3-schema-driven-development">3. Schema-Driven Development </h3>
|
||
|
|
<p><strong>Scenario</strong>: Use schemas to validate and generate documents</p>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Generate schema from example document</span>
|
||
|
|
markitect schema-generate example.md <span class="token parameter variable">--output</span> project-schema.json
|
||
|
|
|
||
|
|
<span class="token comment"># Store schema in database</span>
|
||
|
|
markitect schema-ingest project-schema.json
|
||
|
|
|
||
|
|
<span class="token comment"># Validate documents against schema</span>
|
||
|
|
markitect validate document.md project-schema.json
|
||
|
|
|
||
|
|
<span class="token comment"># Generate stub from schema</span>
|
||
|
|
markitect generate-stub project-schema.json <span class="token parameter variable">--output</span> new-document.md
|
||
|
|
|
||
|
|
<span class="token comment"># Generate multiple drafts</span>
|
||
|
|
markitect generate-drafts project-schema.json data-source.json --output-dir ./drafts/
|
||
|
|
</code></pre><hr>
|
||
|
|
<h2 id="document-processing">Document Processing </h2>
|
||
|
|
<h3 id="batch-processing-techniques">Batch Processing Techniques </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Process multiple files efficiently</span>
|
||
|
|
<span class="token keyword keyword-for">for</span> <span class="token for-or-select variable">file</span> <span class="token keyword keyword-in">in</span> *.md<span class="token punctuation">;</span> <span class="token keyword keyword-do">do</span>
|
||
|
|
markitect ingest <span class="token string">"<span class="token variable">$file</span>"</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"Processed: <span class="token variable">$file</span>"</span>
|
||
|
|
<span class="token keyword keyword-done">done</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Bulk validation</span>
|
||
|
|
<span class="token keyword keyword-for">for</span> <span class="token for-or-select variable">file</span> <span class="token keyword keyword-in">in</span> docs/*.md<span class="token punctuation">;</span> <span class="token keyword keyword-do">do</span>
|
||
|
|
markitect validate <span class="token string">"<span class="token variable">$file</span>"</span> schema.json <span class="token operator">||</span> <span class="token builtin class-name">echo</span> <span class="token string">"Validation failed: <span class="token variable">$file</span>"</span>
|
||
|
|
<span class="token keyword keyword-done">done</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Extract frontmatter from all files</span>
|
||
|
|
markitect list <span class="token parameter variable">--format</span> json <span class="token operator">|</span> jq <span class="token parameter variable">-r</span> <span class="token string">'.[].filename'</span> <span class="token operator">|</span> <span class="token keyword keyword-while">while</span> <span class="token builtin class-name">read</span> <span class="token function">file</span><span class="token punctuation">;</span> <span class="token keyword keyword-do">do</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"=== <span class="token variable">$file</span> ==="</span>
|
||
|
|
markitect frontmatter-keys <span class="token string">"<span class="token variable">$file</span>"</span>
|
||
|
|
<span class="token keyword keyword-done">done</span>
|
||
|
|
</code></pre><h3 id="content-modification-workflows">Content Modification Workflows </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Add sections to existing documents</span>
|
||
|
|
markitect modify document.md --add-section <span class="token string">"New Section"</span> --section-content <span class="token string">"Content here"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Update frontmatter programmatically</span>
|
||
|
|
markitect frontmatter-set document.md <span class="token assign-left variable">last_updated</span><span class="token operator">=</span><span class="token string">"<span class="token variable"><span class="token variable">$(</span><span class="token function">date</span><span class="token variable">)</span></span>"</span>
|
||
|
|
markitect frontmatter-set document.md <span class="token assign-left variable">version</span><span class="token operator">=</span><span class="token number">2.1</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Set contentmatter values</span>
|
||
|
|
markitect contentmatter-set document.md <span class="token assign-left variable">status</span><span class="token operator">=</span>reviewed
|
||
|
|
markitect contentmatter-set document.md <span class="token assign-left variable">project.phase</span><span class="token operator">=</span>complete
|
||
|
|
</code></pre><hr>
|
||
|
|
<h2 id="template--schema-workflows">Template & Schema Workflows </h2>
|
||
|
|
<h3 id="template-driven-document-generation">Template-Driven Document Generation </h3>
|
||
|
|
<p><strong>Scenario</strong>: Generate business documents from templates</p>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Create invoice from template</span>
|
||
|
|
markitect template-render invoice-template.md customer-data.json <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--output</span> <span class="token string">"invoice-<span class="token variable"><span class="token variable">$(</span><span class="token function">date</span> +%Y%m%d<span class="token variable">)</span></span>.md"</span> <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--validate</span> --check-data
|
||
|
|
|
||
|
|
<span class="token comment"># Generate report with YAML data</span>
|
||
|
|
markitect template-render report-template.md quarterly-data.yaml <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--format</span> yaml <span class="token parameter variable">--lenient</span> <span class="token parameter variable">--output</span> quarterly-report.md
|
||
|
|
|
||
|
|
<span class="token comment"># Batch generate documents</span>
|
||
|
|
<span class="token keyword keyword-for">for</span> <span class="token for-or-select variable">customer</span> <span class="token keyword keyword-in">in</span> customers/*.json<span class="token punctuation">;</span> <span class="token keyword keyword-do">do</span>
|
||
|
|
<span class="token assign-left variable">customer_name</span><span class="token operator">=</span><span class="token variable"><span class="token variable">$(</span><span class="token function">basename</span> <span class="token string">"<span class="token variable">$customer</span>"</span> .json<span class="token variable">)</span></span>
|
||
|
|
markitect template-render invoice-template.md <span class="token string">"<span class="token variable">$customer</span>"</span> <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--output</span> <span class="token string">"invoices/invoice-<span class="token variable">$customer_name</span>.md"</span>
|
||
|
|
<span class="token keyword keyword-done">done</span>
|
||
|
|
</code></pre><h3 id="schema-management">Schema Management </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># List all stored schemas</span>
|
||
|
|
markitect schema-list <span class="token parameter variable">--format</span> table
|
||
|
|
|
||
|
|
<span class="token comment"># Export schema for sharing</span>
|
||
|
|
markitect schema-get project-schema <span class="token parameter variable">--output</span> exported-schema.json
|
||
|
|
|
||
|
|
<span class="token comment"># Update schema in database</span>
|
||
|
|
markitect schema-delete old-schema
|
||
|
|
markitect schema-ingest updated-schema.json
|
||
|
|
|
||
|
|
<span class="token comment"># Validate schema compliance</span>
|
||
|
|
markitect validate document.md schema-name --detailed-errors
|
||
|
|
</code></pre><hr>
|
||
|
|
<h2 id="data-analysis--querying">Data Analysis & Querying </h2>
|
||
|
|
<h3 id="database-queries">Database Queries </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># View database schema</span>
|
||
|
|
markitect db-schema
|
||
|
|
|
||
|
|
<span class="token comment"># Query processed files</span>
|
||
|
|
markitect db-query <span class="token string">"SELECT filename, processed_at FROM files WHERE processed_at > '2025-01-01'"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Advanced frontmatter queries</span>
|
||
|
|
markitect db-query <span class="token string">"SELECT filename, frontmatter FROM files WHERE JSON_EXTRACT(frontmatter, '$.author') = 'John Doe'"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Content statistics</span>
|
||
|
|
markitect db-query <span class="token string">"SELECT AVG(JSON_EXTRACT(metadata, '$.word_count')) as avg_words FROM files"</span>
|
||
|
|
</code></pre><h3 id="ast-analysis">AST Analysis </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Query AST structure with JSONPath</span>
|
||
|
|
markitect ast-query document.md <span class="token string">"$.children[?(@.type=='heading')].children[0].value"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Find all links in document</span>
|
||
|
|
markitect ast-query document.md <span class="token string">"$..children[?(@.type=='link')].url"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Extract code blocks</span>
|
||
|
|
markitect ast-query document.md <span class="token string">"$..children[?(@.type=='code')].value"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Analyze heading structure</span>
|
||
|
|
markitect ast-query document.md <span class="token string">"$.children[?(@.type=='heading')].depth"</span> <span class="token parameter variable">--format</span> json
|
||
|
|
</code></pre><h3 id="statistical-analysis">Statistical Analysis </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Document statistics</span>
|
||
|
|
markitect content-stats document.md
|
||
|
|
|
||
|
|
<span class="token comment"># Frontmatter analysis across all files</span>
|
||
|
|
markitect frontmatter-stats
|
||
|
|
|
||
|
|
<span class="token comment"># Contentmatter usage patterns</span>
|
||
|
|
markitect contentmatter-stats
|
||
|
|
|
||
|
|
<span class="token comment"># System performance metrics</span>
|
||
|
|
markitect cache-stats
|
||
|
|
markitect ast-stats
|
||
|
|
</code></pre><hr>
|
||
|
|
<h2 id="advanced-techniques">Advanced Techniques </h2>
|
||
|
|
<h3 id="command-chaining--pipelines">Command Chaining & Pipelines </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Extract and process frontmatter</span>
|
||
|
|
markitect frontmatter-get document.md title <span class="token operator">|</span> <span class="token function">tr</span> <span class="token string">'[:lower:]'</span> <span class="token string">'[:upper:]'</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Combine with standard tools</span>
|
||
|
|
markitect list <span class="token parameter variable">--format</span> json <span class="token operator">|</span> jq <span class="token string">'.[] | select(.word_count > 1000) | .filename'</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Template generation pipeline</span>
|
||
|
|
markitect schema-generate source.md <span class="token operator">|</span> <span class="token punctuation">\</span>
|
||
|
|
markitect generate-stub <span class="token parameter variable">--stdin</span> <span class="token operator">|</span> <span class="token punctuation">\</span>
|
||
|
|
markitect template-render <span class="token parameter variable">--stdin</span> data.json
|
||
|
|
</code></pre><h3 id="conditional-processing">Conditional Processing </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Process only if file changed</span>
|
||
|
|
<span class="token keyword keyword-if">if</span> <span class="token punctuation">[</span> document.md <span class="token parameter variable">-nt</span> last-processed.timestamp <span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token keyword keyword-then">then</span>
|
||
|
|
markitect ingest document.md
|
||
|
|
<span class="token function">touch</span> last-processed.timestamp
|
||
|
|
<span class="token keyword keyword-fi">fi</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Validate before publishing</span>
|
||
|
|
<span class="token keyword keyword-if">if</span> markitect validate document.md schema.json --quiet<span class="token punctuation">;</span> <span class="token keyword keyword-then">then</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"✅ Document valid - ready for publish"</span>
|
||
|
|
markitect template-render publish-template.md document-data.json
|
||
|
|
<span class="token keyword keyword-else">else</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"❌ Validation failed - fix errors first"</span>
|
||
|
|
markitect validate document.md schema.json --detailed-errors
|
||
|
|
<span class="token keyword keyword-fi">fi</span>
|
||
|
|
</code></pre><h3 id="output-format-optimization">Output Format Optimization </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Machine-readable output</span>
|
||
|
|
markitect list <span class="token parameter variable">--format</span> json <span class="token operator">></span> files.json
|
||
|
|
markitect stats <span class="token parameter variable">--format</span> yaml <span class="token operator">></span> stats.yaml
|
||
|
|
|
||
|
|
<span class="token comment"># Human-readable reports</span>
|
||
|
|
markitect list <span class="token parameter variable">--format</span> table --names-only
|
||
|
|
markitect db-stats <span class="token parameter variable">--format</span> simple
|
||
|
|
|
||
|
|
<span class="token comment"># Export for external tools</span>
|
||
|
|
markitect db-query <span class="token string">"SELECT * FROM files"</span> <span class="token parameter variable">--format</span> json <span class="token operator">|</span> jq <span class="token string">'.[] | .filename'</span>
|
||
|
|
</code></pre><hr>
|
||
|
|
<h2 id="business-document-automation">Business Document Automation </h2>
|
||
|
|
<h3 id="invoice-generation-workflow">Invoice Generation Workflow </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Setup: Create invoice template and customer database</span>
|
||
|
|
<span class="token comment"># invoice-template.md contains {{customer.name}}, {{items}}, {{total}} etc.</span>
|
||
|
|
<span class="token comment"># customers.json contains customer data array</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Generate monthly invoices</span>
|
||
|
|
markitect template-render templates/invoice.md data/customer-001.json <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--output</span> <span class="token string">"invoices/<span class="token variable"><span class="token variable">$(</span><span class="token function">date</span> +%Y-%m<span class="token variable">)</span></span>/customer-001-invoice.md"</span> <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--validate</span> --check-data
|
||
|
|
|
||
|
|
<span class="token comment"># Batch invoice generation</span>
|
||
|
|
<span class="token keyword keyword-for">for</span> <span class="token for-or-select variable">customer</span> <span class="token keyword keyword-in">in</span> data/customers/*.json<span class="token punctuation">;</span> <span class="token keyword keyword-do">do</span>
|
||
|
|
<span class="token assign-left variable">customer_id</span><span class="token operator">=</span><span class="token variable"><span class="token variable">$(</span><span class="token function">basename</span> <span class="token string">"<span class="token variable">$customer</span>"</span> .json<span class="token variable">)</span></span>
|
||
|
|
markitect template-render templates/invoice.md <span class="token string">"<span class="token variable">$customer</span>"</span> <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--output</span> <span class="token string">"invoices/<span class="token variable"><span class="token variable">$(</span><span class="token function">date</span> +%Y-%m<span class="token variable">)</span></span>/<span class="token variable">$customer_id</span>-invoice.md"</span> <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--strict</span>
|
||
|
|
<span class="token keyword keyword-done">done</span>
|
||
|
|
</code></pre><h3 id="report-generation-pipeline">Report Generation Pipeline </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Generate quarterly business report</span>
|
||
|
|
markitect template-render templates/quarterly-report.md data/q1-2025.yaml <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--format</span> yaml <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--output</span> <span class="token string">"reports/Q1-2025-Business-Report.md"</span> <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--validate</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Validate report against company standards</span>
|
||
|
|
markitect validate <span class="token string">"reports/Q1-2025-Business-Report.md"</span> schemas/report-schema.json
|
||
|
|
|
||
|
|
<span class="token comment"># Extract key metrics for dashboard</span>
|
||
|
|
markitect frontmatter-get <span class="token string">"reports/Q1-2025-Business-Report.md"</span> metrics.revenue
|
||
|
|
markitect contentmatter-get <span class="token string">"reports/Q1-2025-Business-Report.md"</span> kpi.growth_rate
|
||
|
|
</code></pre><h3 id="content-management-workflows">Content Management Workflows </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Blog post publishing pipeline</span>
|
||
|
|
markitect ingest drafts/new-post.md
|
||
|
|
markitect validate drafts/new-post.md schemas/blog-post.json
|
||
|
|
markitect frontmatter-set drafts/new-post.md <span class="token assign-left variable">published_date</span><span class="token operator">=</span><span class="token string">"<span class="token variable"><span class="token variable">$(</span><span class="token function">date</span><span class="token variable">)</span></span>"</span>
|
||
|
|
markitect frontmatter-set drafts/new-post.md <span class="token assign-left variable">status</span><span class="token operator">=</span>published
|
||
|
|
|
||
|
|
<span class="token comment"># Documentation maintenance</span>
|
||
|
|
markitect schema-generate docs/api-reference.md <span class="token parameter variable">--output</span> schemas/api-doc.json
|
||
|
|
markitect generate-stub schemas/api-doc.json <span class="token parameter variable">--output</span> templates/api-template.md
|
||
|
|
|
||
|
|
<span class="token comment"># Quality assurance checks</span>
|
||
|
|
markitect tailmatter-check document.md <span class="token comment"># Run QA checklist</span>
|
||
|
|
markitect validate document.md company-standards.json --detailed-errors
|
||
|
|
</code></pre><hr>
|
||
|
|
<h2 id="troubleshooting--optimization">Troubleshooting & Optimization </h2>
|
||
|
|
<h3 id="performance-optimization">Performance Optimization </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Check cache effectiveness</span>
|
||
|
|
markitect cache-stats
|
||
|
|
|
||
|
|
<span class="token comment"># Clean cache if needed</span>
|
||
|
|
markitect cache-clean
|
||
|
|
|
||
|
|
<span class="token comment"># Invalidate specific file cache</span>
|
||
|
|
markitect cache-invalidate problematic-file.md
|
||
|
|
|
||
|
|
<span class="token comment"># Monitor database performance</span>
|
||
|
|
markitect db-stats <span class="token parameter variable">--format</span> json <span class="token operator">|</span> jq <span class="token string">'.performance'</span>
|
||
|
|
</code></pre><h3 id="debugging-workflows">Debugging Workflows </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Verbose output for debugging</span>
|
||
|
|
markitect <span class="token parameter variable">--verbose</span> ingest document.md
|
||
|
|
|
||
|
|
<span class="token comment"># Check file processing status</span>
|
||
|
|
markitect metadata document.md <span class="token parameter variable">--format</span> json <span class="token operator">|</span> jq <span class="token string">'.processing_errors'</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Validate template syntax</span>
|
||
|
|
markitect template-render template.md data.json <span class="token parameter variable">--validate</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Debug AST issues</span>
|
||
|
|
markitect ast-show document.md <span class="token parameter variable">--format</span> json <span class="token operator">|</span> jq <span class="token string">'.errors'</span>
|
||
|
|
</code></pre><h3 id="database-maintenance">Database Maintenance </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Backup database</span>
|
||
|
|
<span class="token function">cp</span> markitect.db markitect-backup-<span class="token variable"><span class="token variable">$(</span><span class="token function">date</span> +%Y%m%d<span class="token variable">)</span></span>.db
|
||
|
|
|
||
|
|
<span class="token comment"># Clean up orphaned records</span>
|
||
|
|
markitect db-query <span class="token string">"DELETE FROM files WHERE filename NOT IN (SELECT DISTINCT filename FROM current_files)"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Optimize database</span>
|
||
|
|
markitect db-query <span class="token string">"VACUUM"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Check database integrity</span>
|
||
|
|
markitect db-query <span class="token string">"PRAGMA integrity_check"</span>
|
||
|
|
</code></pre><h3 id="configuration-management">Configuration Management </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Check configuration</span>
|
||
|
|
markitect config-stats
|
||
|
|
|
||
|
|
<span class="token comment"># Use custom config file</span>
|
||
|
|
markitect <span class="token parameter variable">--config</span> custom-config.yaml list
|
||
|
|
|
||
|
|
<span class="token comment"># Use different database</span>
|
||
|
|
markitect <span class="token parameter variable">--database</span> project-specific.db ingest document.md
|
||
|
|
</code></pre><hr>
|
||
|
|
<h2 id="pro-tips--best-practices">Pro Tips & Best Practices </h2>
|
||
|
|
<h3 id="1-workflow-automation">1. Workflow Automation </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Create alias for common operations</span>
|
||
|
|
<span class="token builtin class-name">alias</span> md-process<span class="token operator">=</span><span class="token string">'markitect ingest'</span>
|
||
|
|
<span class="token builtin class-name">alias</span> md-validate<span class="token operator">=</span><span class="token string">'markitect validate'</span>
|
||
|
|
<span class="token builtin class-name">alias</span> md-extract<span class="token operator">=</span><span class="token string">'markitect frontmatter-get'</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Setup environment variables</span>
|
||
|
|
<span class="token builtin class-name">export</span> <span class="token assign-left variable">MARKITECT_DB</span><span class="token operator">=</span><span class="token string">"/path/to/project.db"</span>
|
||
|
|
<span class="token builtin class-name">export</span> <span class="token assign-left variable">MARKITECT_CONFIG</span><span class="token operator">=</span><span class="token string">"/path/to/config.yaml"</span>
|
||
|
|
</code></pre><h3 id="2-error-handling-in-scripts">2. Error Handling in Scripts </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token shebang important">#!/bin/bash</span>
|
||
|
|
<span class="token comment"># Robust document processing script</span>
|
||
|
|
|
||
|
|
<span class="token function-name function">process_document</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||
|
|
<span class="token builtin class-name">local</span> <span class="token assign-left variable">file</span><span class="token operator">=</span><span class="token string">"<span class="token variable">$1</span>"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Check file exists</span>
|
||
|
|
<span class="token keyword keyword-if">if</span> <span class="token punctuation">[</span><span class="token punctuation">[</span> <span class="token operator">!</span> <span class="token parameter variable">-f</span> <span class="token string">"<span class="token variable">$file</span>"</span> <span class="token punctuation">]</span><span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token keyword keyword-then">then</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"Error: File <span class="token variable">$file</span> not found"</span> <span class="token operator">></span><span class="token file-descriptor important">&2</span>
|
||
|
|
<span class="token builtin class-name">return</span> <span class="token number">1</span>
|
||
|
|
<span class="token keyword keyword-fi">fi</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Process with error handling</span>
|
||
|
|
<span class="token keyword keyword-if">if</span> markitect ingest <span class="token string">"<span class="token variable">$file</span>"</span><span class="token punctuation">;</span> <span class="token keyword keyword-then">then</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"✅ Processed: <span class="token variable">$file</span>"</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Validate if schema exists</span>
|
||
|
|
<span class="token keyword keyword-if">if</span> <span class="token punctuation">[</span><span class="token punctuation">[</span> <span class="token parameter variable">-f</span> <span class="token string">"schema.json"</span> <span class="token punctuation">]</span><span class="token punctuation">]</span><span class="token punctuation">;</span> <span class="token keyword keyword-then">then</span>
|
||
|
|
<span class="token keyword keyword-if">if</span> markitect validate <span class="token string">"<span class="token variable">$file</span>"</span> schema.json --quiet<span class="token punctuation">;</span> <span class="token keyword keyword-then">then</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"✅ Validated: <span class="token variable">$file</span>"</span>
|
||
|
|
<span class="token keyword keyword-else">else</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"⚠️ Validation failed: <span class="token variable">$file</span>"</span> <span class="token operator">></span><span class="token file-descriptor important">&2</span>
|
||
|
|
markitect validate <span class="token string">"<span class="token variable">$file</span>"</span> schema.json --detailed-errors <span class="token operator">></span><span class="token file-descriptor important">&2</span>
|
||
|
|
<span class="token keyword keyword-fi">fi</span>
|
||
|
|
<span class="token keyword keyword-fi">fi</span>
|
||
|
|
<span class="token keyword keyword-else">else</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"❌ Processing failed: <span class="token variable">$file</span>"</span> <span class="token operator">></span><span class="token file-descriptor important">&2</span>
|
||
|
|
<span class="token builtin class-name">return</span> <span class="token number">1</span>
|
||
|
|
<span class="token keyword keyword-fi">fi</span>
|
||
|
|
<span class="token punctuation">}</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Process all markdown files</span>
|
||
|
|
<span class="token keyword keyword-for">for</span> <span class="token for-or-select variable">file</span> <span class="token keyword keyword-in">in</span> *.md<span class="token punctuation">;</span> <span class="token keyword keyword-do">do</span>
|
||
|
|
process_document <span class="token string">"<span class="token variable">$file</span>"</span> <span class="token operator">||</span> <span class="token builtin class-name">echo</span> <span class="token string">"Skipping <span class="token variable">$file</span> due to errors"</span>
|
||
|
|
<span class="token keyword keyword-done">done</span>
|
||
|
|
</code></pre><h3 id="3-integration-with-other-tools">3. Integration with Other Tools </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Combine with git hooks</span>
|
||
|
|
<span class="token comment"># .git/hooks/pre-commit</span>
|
||
|
|
markitect validate changed-docs/*.md schemas/doc-standard.json <span class="token parameter variable">--quiet</span> <span class="token operator">||</span> <span class="token punctuation">{</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"Documentation validation failed"</span>
|
||
|
|
<span class="token builtin class-name">exit</span> <span class="token number">1</span>
|
||
|
|
<span class="token punctuation">}</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Integration with CI/CD</span>
|
||
|
|
markitect list <span class="token parameter variable">--format</span> json <span class="token operator">|</span> jq <span class="token parameter variable">-r</span> <span class="token string">'.[] | select(.validation_status != "valid") | .filename'</span> <span class="token operator">|</span> <span class="token keyword keyword-while">while</span> <span class="token builtin class-name">read</span> <span class="token function">file</span><span class="token punctuation">;</span> <span class="token keyword keyword-do">do</span>
|
||
|
|
<span class="token builtin class-name">echo</span> <span class="token string">"::error file=<span class="token variable">$file</span>::Document validation failed"</span>
|
||
|
|
<span class="token keyword keyword-done">done</span>
|
||
|
|
|
||
|
|
<span class="token comment"># Export for external analytics</span>
|
||
|
|
markitect db-query <span class="token string">"SELECT filename, JSON_EXTRACT(metadata, '$.word_count') as words FROM files"</span> <span class="token punctuation">\</span>
|
||
|
|
<span class="token parameter variable">--format</span> json <span class="token operator">|</span> jq <span class="token parameter variable">-r</span> <span class="token string">'.[] | "\(.filename),\(.words)"'</span> <span class="token operator">></span> document-metrics.csv
|
||
|
|
</code></pre><hr>
|
||
|
|
<h2 id="quick-reference">Quick Reference </h2>
|
||
|
|
<h3 id="most-common-commands">Most Common Commands </h3>
|
||
|
|
<pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Basic document processing</span>
|
||
|
|
markitect ingest document.md
|
||
|
|
markitect list
|
||
|
|
markitect stats document.md
|
||
|
|
|
||
|
|
<span class="token comment"># Content extraction</span>
|
||
|
|
markitect frontmatter-get document.md key
|
||
|
|
markitect content-get document.md
|
||
|
|
|
||
|
|
<span class="token comment"># Template processing</span>
|
||
|
|
markitect template-render template.md data.json
|
||
|
|
|
||
|
|
<span class="token comment"># Schema operations</span>
|
||
|
|
markitect schema-generate document.md
|
||
|
|
markitect validate document.md schema.json
|
||
|
|
|
||
|
|
<span class="token comment"># Database queries</span>
|
||
|
|
markitect db-query <span class="token string">"SQL_QUERY"</span>
|
||
|
|
markitect list <span class="token parameter variable">--format</span> json
|
||
|
|
</code></pre><h3 id="output-formats">Output Formats </h3>
|
||
|
|
<ul>
|
||
|
|
<li><code>--format table</code> - Human-readable tables</li>
|
||
|
|
<li><code>--format json</code> - Machine-readable JSON</li>
|
||
|
|
<li><code>--format yaml</code> - YAML format</li>
|
||
|
|
<li><code>--format simple</code> - Plain text</li>
|
||
|
|
<li><code>--format compact</code> - Condensed output</li>
|
||
|
|
</ul>
|
||
|
|
<h3 id="global-options">Global Options </h3>
|
||
|
|
<ul>
|
||
|
|
<li><code>--verbose</code> - Detailed output</li>
|
||
|
|
<li><code>--config CONFIG_FILE</code> - Custom configuration</li>
|
||
|
|
<li><code>--database DB_FILE</code> - Custom database</li>
|
||
|
|
<li><code>--help</code> - Command help</li>
|
||
|
|
</ul>
|
||
|
|
<hr>
|
||
|
|
<p><strong>🎯 Pro Tip</strong>: Start with basic <code>ingest</code> and <code>list</code> commands, then gradually explore advanced features. Use <code>--help</code> on any command to see all available options!</p>
|
||
|
|
<p><strong>📚 Remember</strong>: MarkiTect is designed for powerful document automation - combine commands creatively to build sophisticated workflows that match your specific needs.</p>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body></html>
|