Skip to content

feat: Cross-Document Link Validator, Graph Analyzer, CLI Refactor #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eli64s wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Cross-Document Link Validator, Graph Analyzer, CLI Refactor #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
691 changes: 691 additions & 0 deletions docs/docmodel_engine/README.md
View file
Open in desktop

Large diffs are not rendered by default.

533 changes: 533 additions & 0 deletions docs/docmodel_engine/advanced_docmodel_engine.md
View file
Open in desktop

Large diffs are not rendered by default.

593 changes: 593 additions & 0 deletions docs/docmodel_engine/archetypes.md
View file
Open in desktop

Large diffs are not rendered by default.

434 changes: 434 additions & 0 deletions docs/docmodel_engine/ci_cd_integration_cli.md
View file
Open in desktop

Large diffs are not rendered by default.

458 changes: 458 additions & 0 deletions docs/docmodel_engine/context_awareness_consistency.md
View file
Open in desktop

Large diffs are not rendered by default.

442 changes: 442 additions & 0 deletions docs/docmodel_engine/context_awareness_syntax.md
View file
Open in desktop

Large diffs are not rendered by default.

383 changes: 383 additions & 0 deletions docs/docmodel_engine/ide_integration_lsp_basic.md
View file
Open in desktop

Large diffs are not rendered by default.

277 changes: 277 additions & 0 deletions docs/docmodel_engine/internal_structure_map.md
View file
Open in desktop

Large diffs are not rendered by default.

292 changes: 292 additions & 0 deletions docs/docmodel_engine/non_functional_requirements_phase0.md
View file
Open in desktop

Large diffs are not rendered by default.

178 changes: 23 additions & 155 deletions docs/guides/cli-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,32 +11,20 @@ Markitecture provides a comprehensive command-line interface with several main c
<Card title="split" icon="scissors">
Split markdown files into sections based on headings
</Card>
<Card title="check-links" icon="link-check">
Validate links in markdown documents
</Card>
<Card title="reflinks" icon="arrows-repeat">
Convert inline links to reference style
</Card>
<Card title="mkdocs" icon="book">
Generate MkDocs configuration
</Card>
<Card title="config" icon="gear">
Manage Markitecture configuration
</Card>
<Card title="metrics" icon="chart-line">
Generate document metrics
<Card title="links" icon="link-check">
Validate links in markdown documents and convert inline links to reference style
</Card>
</CardGroup>

## Basic Usage

<CodeGroup>
<CodeBlock title="Help" language="bash">
markitect --help
markitecture --help
</CodeBlock>

<CodeBlock title="Version" language="bash">
markitect --version
markitecture --version
</CodeBlock>
</CodeGroup>

Expand All @@ -46,180 +34,66 @@ Markitecture provides a comprehensive command-line interface with several main c

Split markdown files into sections based on headings.

<ResponseField name="--split.i, --split.input" type="Path" required>
<ResponseField name="input_path" type="Path" required>
Path to the input markdown file
</ResponseField>

<ResponseField name="--split.o, --split.output" type="Path" default=".markitecture/docs">
<ResponseField name="output_dir" type="Path" required>
Directory to save split files
</ResponseField>

<ResponseField name="--split.hl, --split.heading-level" type="string" default="##">
Heading level to split on (e.g., '#', '##')
</ResponseField>

<ResponseField name="--split.cs, --split.case-sensitive" type="boolean" default="false">
Enable case-sensitive heading matching
<ResponseField name="--level" type="integer" default="2">
The markdown heading level to split by.
</ResponseField>

<CodeGroup>
<CodeBlock title="Basic Split" language="bash">
markitect --split.i README.md --split.o docs/
markitecture split README.md docs/
</CodeBlock>

<CodeBlock title="Custom Heading" language="bash">
markitect --split.i README.md --split.hl "###" --split.cs
markitecture split README.md docs/ --level 3
</CodeBlock>
</CodeGroup>

### Check Links Command
### Links Command

Validate links in markdown documents.
Commands for checking and converting markdown links.

<ResponseField name="--check-links.i, --check-links.input" type="Path" required>
Path to the markdown file
</ResponseField>
#### `check`

<ResponseField name="--check-links.rp, --check-links.report-path" type="Path" default=".markitecture/link_health.txt">
Path to save the report
</ResponseField>

<ResponseField name="--check-links.mw, --check-links.max-workers" type="integer" default="5">
Number of concurrent link checks
</ResponseField>
Validate links in markdown documents.

<ResponseField name="--check-links.t, --check-links.timeout" type="integer" default="10">
Timeout for link validation in seconds
<ResponseField name="path" type="Path" required>
Path to the markdown file or directory to check.
</ResponseField>

<CodeGroup>
<CodeBlock title="Basic Check" language="bash">
markitect --check-links.i docs/index.md
</CodeBlock>

<CodeBlock title="Custom Settings" language="bash">
markitect --check-links.i docs/*.md --check-links.mw 10 --check-links.t 20
markitecture links check docs/index.md
</CodeBlock>
</CodeGroup>

### Reference Links Command
#### `reflinks`

Convert inline links to reference style.

<ResponseField name="--reflinks.i, --reflinks.input" type="Path" required>
Path to the markdown file
</ResponseField>

<ResponseField name="--reflinks.o, --reflinks.output" type="Path" default="reflinks_output.md">
Path to save updated document
<ResponseField name="path" type="Path" required>
Path to the markdown file or directory to convert.
</ResponseField>

<CodeGroup>
<CodeBlock title="Basic Conversion" language="bash">
markitect --reflinks.i docs/guide.md
</CodeBlock>

<CodeBlock title="Custom Output" language="bash">
markitect --reflinks.i input.md --reflinks.o converted.md
</CodeBlock>
</CodeGroup>

### MkDocs Command

Generate MkDocs configuration.

<ResponseField name="--mkdocs.d, --mkdocs.dir" type="Path" default=".markitecture/docs">
Path to the documentation directory
</ResponseField>

<ResponseField name="--mkdocs.name, --mkdocs.site-name" type="string" default="MkDocs Static Site Documentation">
Name of the MkDocs site
</ResponseField>

<CodeGroup>
<CodeBlock title="Basic Setup" language="bash">
markitect --mkdocs.d docs/
</CodeBlock>

<CodeBlock title="Custom Site" language="bash">
markitect --mkdocs.d docs/ --mkdocs.name "My Project Docs"
</CodeBlock>
</CodeGroup>

### Config Command

Manage Markitecture configuration.

<ResponseField name="--config.p, --config.path" type="Path" default="markitect.yml">
Path to the configuration file
</ResponseField>

<ResponseField name="--config.g, --config.generate" type="boolean" default="false">
Generate a default configuration file
</ResponseField>

<ResponseField name="--config.s, --config.show" type="boolean" default="false">
Display the current configuration settings
</ResponseField>

<CodeGroup>
<CodeBlock title="Generate Config" language="bash">
markitect --config.generate
</CodeBlock>

<CodeBlock title="Show Config" language="bash">
markitect --config.show
</CodeBlock>
</CodeGroup>

### Metrics Command

Generate document readability metrics.

<ResponseField name="--metrics.i, --metrics.input" type="Path" required>
Path to the markdown file
</ResponseField>

<ResponseField name="--metrics.o, --metrics.output" type="Path">
Path to save the SVG badge
</ResponseField>

<ResponseField name="--metrics.style" type="enum" default="MODERN">
Badge style options: MODERN, COMPACT, DETAILED, MINIMAL, RETRO, SHIELDS
</ResponseField>

<ResponseField name="--metrics.p, --metrics.position" type="string" default="top">
Position to insert badge (top/bottom)
</ResponseField>

<CodeGroup>
<CodeBlock title="Basic Metrics" language="bash">
markitect --metrics.i docs/guide.md
</CodeBlock>

<CodeBlock title="Custom Style" language="bash">
markitect --metrics.i input.md --metrics.style DETAILED --metrics.p bottom
markitecture links reflinks docs/guide.md
</CodeBlock>
</CodeGroup>

## Environment Variables

All command-line options can be set using environment variables with the `MARKITECTURE_` prefix:

<ResponseField name="MARKITECTURE_HEADING_LEVEL" type="string">
Default heading level for splitting
</ResponseField>

<ResponseField name="MARKITECTURE_OUTPUT_DIR" type="string">
Default output directory
</ResponseField>

<ResponseField name="MARKITECTURE_PRESERVE_REFS" type="boolean">
Whether to preserve reference links
</ResponseField>

<ResponseField name="MARKITECTURE_ADD_HR" type="boolean">
Whether to add horizontal rules between sections
<ResponseField name="MARKITECTURE_OPENAI_API_KEY" type="string">
Your OpenAI API key.
</ResponseField>

## Exit Codes
Expand All @@ -231,12 +105,6 @@ All command-line options can be set using environment variables with the `MARKIT
<Card title="1">
Error - General error occurred
</Card>
<Card title="2">
Config Error - Configuration error
</Card>
<Card title="3">
File Error - File operation failed
</Card>
</CardGroup>

<Note>
Expand Down
140 changes: 1 addition & 139 deletions examples/reference-links/convert-links.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,139 +1 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Reference Links"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"from pathlib import Path\n",
"\n",
"Path.mkdir(Path.cwd(), exist_ok=True)\n",
"path = Path.cwd()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Convert Links\n",
"\n",
"Links can be converted to reference link syntax. This method will convert *ALL* inline links to reference links.\n",
"\n",
"Additionnaly, you can select where to place the reference links:\n",
"1. At the end of the document (default)\n",
"2. At the end of the heading section they are in"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Initialize the Converter"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"from markitecture import ReferenceLinkConverter\n",
"\n",
"converter = ReferenceLinkConverter()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### End of Document"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [],
"source": [
"from markitecture import ReferenceLinkConverter, ReferencePlacement\n",
"\n",
"converter = ReferenceLinkConverter().process_file(\n",
" \"../../tests/data/pydantic.md\",\n",
" \"../../examples/reference-links/convert_pydantic.md\",\n",
" ReferencePlacement.SECTION,\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### End of Document"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [],
"source": [
"ReferenceLinkConverter().process_file(\n",
" input_path=\"../../tests/data/readme-ai.md\",\n",
" output_path=\"../../examples/reference-links/convert_readmeai.md\",\n",
" placement=ReferencePlacement.END,\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"converter = ReferenceLinkConverter()\n",
"updated_content = converter.convert_to_reflinks(\n",
" content=\"../../tests/data/pydantic.md\",\n",
" naming=\"../../tests/data/pydantic.md\",\n",
" placement=ReferencePlacement.SECTION,\n",
")\n",
"print(updated_content)"
]
}
],
"metadata": {
"kernelspec": {
"display_name": ".venv",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.10"
}
},
"nbformat": 4,
"nbformat_minor": 2
}
{"cells": [{"cell_type": "markdown", "metadata": {}, "source": ["# Convert Inline Links to Reference Links (In-Place)"]}, {"cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": ["!markitect links reflinks --input /samples/in-place-conversion.md"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Verify the content of `in-place-conversion.md` to see the changes."]}, {"cell_type": "markdown", "metadata": {}, "source": ["# Convert Inline Links to Reference Links (New File)"]}, {"cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": ["!markitect links reflinks --input /samples/input.md --output /samples/output.md"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Verify the content of `output.md` to see the changes."]}], "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.12"}}, "nbformat": 4, "nbformat_minor": 5}
Loading
Loading