coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions 1 Projects 12 Releases 1 Wiki Activity
Files
dbbf06db896b2ef965a2cb01c2de0863db6426e7
markitect-main/CLI_TUTORIAL.html
tegwick 960a7c4850 feat: Complete CLI consolidation - fix redundancy and missing interfaces 
🎯 MAJOR CLI ARCHITECTURE CONSOLIDATION:

✅ Added Missing CLI Entry Points:
• tddai = "tddai_cli:main" - TDD workflow management
• issue = "cli.issue_cli:main" - Pure issue management
• All three CLIs now properly installed: markitect, tddai, issue

🧹 Eliminated Functionality Redundancy:
• Removed issue commands from markitect/cli.py (clean separation)
• MarkiTect now focuses purely on document processing
• TDD workflow in tddai CLI, issue management in issue CLI

🏗️ Clean Architecture Implementation:
• Created cli/issue_cli.py - Dedicated pure issue management
• Enhanced cli/commands/export.py with export_issues_csv/json
• Updated cli/core.py with proper export method delegation
• Fixed pyproject.toml to include all required packages

🧪 Comprehensive Testing:
• Added tests/test_cli_consolidation.py - Prevents CLI regression
• Tests ensure all CLIs are installed and functional
• Tests verify no functionality duplication
• Regression protection against missing CLI commands

📋 Clear Separation of Concerns:
• markitect CLI - Document processing, templates, performance
• tddai CLI - TDD workflow, workspace management, coverage
• issue CLI - Pure issue operations, project management, export

🔧 Package Configuration:
• Updated pyproject.toml to include cli*, tddai*, services*, etc.
• Added py-modules for tddai_cli standalone module
• Fixed import paths and dependencies

This consolidation resolves the major redundancy identified in issues
functionality and ensures proper CLI interfaces are available and tested.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-02 23:04:57 +02:00

457 lines
48 KiB
HTML
Raw Blame History

<!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 body>ul{margin-bottom:16px}html body ol,html body ul{padding-left:2em}html body ol.no-list,html body ul.no-list{padding:0;list-style-type:none}html body ol ol,html body ol ul,html body ul ol,html body ul ul{margin-top:0;margin-bottom:0}html body li{margin-bottom:0}html body li.task-list-item{list-style:none}html body li>p{margin-top:0;margin-bottom:0}html body .task-list-item-checkbox{margin:0 .2em .25em -1.8em;vertical-align:middle}html body .task-list-item-checkbox:hover{cursor:pointer}html body blockquote{margin:16px 0;font-size:inherit;padding:0 15px;color:#5c5c5c;background-color:#f0f0f0;border-left:4px solid #d6d6d6}html body blockquote>:first-child{margin-top:0}html body blockquote>:last-child{margin-bottom:0}html body hr{height:4px;margin:32px 0;background-color:#d6d6d6;border:0 none}html body table{margin:10px 0 15px 0;border-collapse:collapse;border-spacing:0;display:block;width:100%;overflow:auto;word-break:normal;word-break:keep-all}html body table th{font-weight:700;color:#000}html body table td,html body table th{border:1px solid #d6d6d6;padding:6px 13px}html body dl{padding:0}html body dl dt{padding:0;margin-top:16px;font-size:1em;font-style:italic;font-weight:700}html body dl dd{padding:0 16px;margin-bottom:16px}html body code{font-family:Menlo,Monaco,Consolas,'Courier New',monospace;font-size:.85em;color:#000;background-color:#f0f0f0;border-radius:3px;padding:.2em 0}html body code::after,html body code::before{letter-spacing:-.2em;content:'\00a0'}html body pre>code{padding:0;margin:0;word-break:normal;white-space:pre;background:0 0;border:0}html body .highlight{margin-bottom:16px}html body .highlight pre,html body pre{padding:1em;overflow:auto;line-height:1.45;border:#d6d6d6;border-radius:3px}html body .highlight pre{margin-bottom:0;word-break:normal}html body pre code,html body pre tt{display:inline;max-width:initial;padding:0;margin:0;overflow:initial;line-height:inherit;word-wrap:normal;background-color:transparent;border:0}html body pre code:after,html body pre code:before,html body pre tt:after,html body pre tt:before{content:normal}html body blockquote,html body dl,html body ol,html body p,html body pre,html body ul{margin-top:0;margin-bottom:16px}html body kbd{color:#000;border:1px solid #d6d6d6;border-bottom:2px solid #c7c7c7;padding:2px 4px;background-color:#f0f0f0;border-radius:3px}@media print{html body{background-color:#fff}html body h1,html body h2,html body h3,html body h4,html body h5,html body h6{color:#000;page-break-after:avoid}html body blockquote{color:#5c5c5c}html body pre{page-break-inside:avoid}html body table{display:table}html body img{display:block;max-width:100%;max-height:100%}html body code,html body pre{word-wrap:break-word;white-space:pre}}.markdown-preview{width:100%;height:100%;box-sizing:border-box}.markdown-preview ul{list-style:disc}.markdown-preview ul ul{list-style:circle}.markdown-preview ul ul ul{list-style:square}.markdown-preview ol{list-style:decimal}.markdown-preview ol ol,.markdown-preview ul ol{list-style-type:lower-roman}.markdown-preview ol ol ol,.markdown-preview ol ul ol,.markdown-preview ul ol ol,.markdown-preview ul ul ol{list-style-type:lower-alpha}.markdown-preview .newpage,.markdown-preview .pagebreak{page-break-before:always}.markdown-preview pre.line-numbers{position:relative;padding-left:3.8em;counter-reset:linenumber}.markdown-preview pre.line-numbers>code{position:relative}.markdown-preview pre.line-numbers .line-numbers-rows{position:absolute;pointer-events:none;top:1em;font-size:100%;left:0;width:3em;letter-spacing:-1px;border-right:1px solid #999;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.markdown-preview pre.line-numbers .line-numbers-rows>span{pointer-events:none;display:block;counter-increment:linenumber}.markdown-preview pre.line-numbers .line-numbers-rows>span:before{content:counter(linenumber);color:#999;display:block;padding-right:.8em;text-align:right}.markdown-preview .mathjax-exps .MathJax_Display{text-align:center!important}.markdown-preview:not([data-for=preview]) .code-chunk .code-chunk-btn-group{display:none}.markdown-preview:not([data-for=preview]) .code-chunk .status{display:none}.markdown-preview:not([data-for=preview]) .code-chunk .output-div{margin-bottom:16px}.markdown-preview .md-toc{padding:0}.markdown-preview .md-toc .md-toc-link-wrapper .md-toc-link{display:inline;padding:.25rem 0}.markdown-preview .md-toc .md-toc-link-wrapper .md-toc-link div,.markdown-preview .md-toc .md-toc-link-wrapper .md-toc-link p{display:inline}.markdown-preview .md-toc .md-toc-link-wrapper.highlighted .md-toc-link{font-weight:800}.scrollbar-style::-webkit-scrollbar{width:8px}.scrollbar-style::-webkit-scrollbar-track{border-radius:10px;background-color:transparent}.scrollbar-style::-webkit-scrollbar-thumb{border-radius:5px;background-color:rgba(150,150,150,.66);border:4px solid rgba(150,150,150,.66);background-clip:content-box}html body[for=html-export]:not([data-presentation-mode]){position:relative;width:100%;height:100%;top:0;left:0;margin:0;padding:0;overflow:auto}html body[for=html-export]:not([data-presentation-mode]) .markdown-preview{position:relative;top:0;min-height:100vh}@media screen and (min-width:914px){html body[for=html-export]:not([data-presentation-mode]) .markdown-preview{padding:2em calc(50% - 457px + 2em)}}@media screen and (max-width:914px){html body[for=html-export]:not([data-presentation-mode]) .markdown-preview{padding:2em}}@media screen and (max-width:450px){html body[for=html-export]:not([data-presentation-mode]) .markdown-preview{font-size:14px!important;padding:1em}}@media print{html body[for=html-export]:not([data-presentation-mode]) #sidebar-toc-btn{display:none}}html body[for=html-export]:not([data-presentation-mode]) #sidebar-toc-btn{position:fixed;bottom:8px;left:8px;font-size:28px;cursor:pointer;color:inherit;z-index:99;width:32px;text-align:center;opacity:.4}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] #sidebar-toc-btn{opacity:1}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc{position:fixed;top:0;left:0;width:300px;height:100%;padding:32px 0 48px 0;font-size:14px;box-shadow:0 0 4px rgba(150,150,150,.33);box-sizing:border-box;overflow:auto;background-color:inherit}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc::-webkit-scrollbar{width:8px}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc::-webkit-scrollbar-track{border-radius:10px;background-color:transparent}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc::-webkit-scrollbar-thumb{border-radius:5px;background-color:rgba(150,150,150,.66);border:4px solid rgba(150,150,150,.66);background-clip:content-box}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc a{text-decoration:none}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc .md-toc{padding:0 16px}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc .md-toc .md-toc-link-wrapper .md-toc-link{display:inline;padding:.25rem 0}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc .md-toc .md-toc-link-wrapper .md-toc-link div,html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc .md-toc .md-toc-link-wrapper .md-toc-link p{display:inline}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .md-sidebar-toc .md-toc .md-toc-link-wrapper.highlighted .md-toc-link{font-weight:800}html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .markdown-preview{left:300px;width:calc(100% - 300px);padding:2em calc(50% - 457px - 300px / 2);margin:0;box-sizing:border-box}@media screen and (max-width:1274px){html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .markdown-preview{padding:2em}}@media screen and (max-width:450px){html body[for=html-export]:not([data-presentation-mode])[html-show-sidebar-toc] .markdown-preview{width:100%}}html body[for=html-export]:not([data-presentation-mode]):not([html-show-sidebar-toc]) .markdown-preview{left:50%;transform:translateX(-50%)}html body[for=html-export]:not([data-presentation-mode]):not([html-show-sidebar-toc]) .md-sidebar-toc{display:none}
/* 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 &amp; Schema Workflows</a></li>
<li><a href="#data-analysis--querying">Data Analysis &amp; 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 &amp; Optimization</a></li>
</ol>
<hr>
<h2 id="getting-started">Getting Started </h2>
<h3 id="installation--first-steps">Installation &amp; 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 &amp; 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 &amp; 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 &gt; '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 &amp; 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 &gt; 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">&gt;</span> files.json
markitect stats <span class="token parameter variable">--format</span> yaml <span class="token operator">&gt;</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 &amp; 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 &amp; 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">&gt;</span><span class="token file-descriptor important">&amp;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">&gt;</span><span class="token file-descriptor important">&amp;2</span>
markitect validate <span class="token string">"<span class="token variable">$file</span>"</span> schema.json --detailed-errors <span class="token operator">&gt;</span><span class="token file-descriptor important">&amp;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">&gt;</span><span class="token file-descriptor important">&amp;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">&gt;</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>
Reference in New Issue View Git Blame Copy Permalink