117 lines
3.7 KiB
Markdown
117 lines
3.7 KiB
Markdown
# MarkiTect Command Migration Guide
|
|
|
|
## Overview
|
|
|
|
As of this release, MarkiTect has migrated the core markdown commands (`ingest`, `get`, `list`) to use prefixed names for consistency with the existing command structure. The new commands use the `md-` prefix.
|
|
|
|
## Command Changes
|
|
|
|
| Old Command | New Command | Status |
|
|
|------------|-------------|---------|
|
|
| `markitect ingest` | `markitect md-ingest` | ✅ Active |
|
|
| `markitect get` | `markitect md-get` | ✅ Active |
|
|
| `markitect list` | `markitect md-list` | ✅ Active |
|
|
|
|
## Migration Timeline
|
|
|
|
- **Immediate**: New `md-` prefixed commands are available
|
|
- **Migration Period**: 1 month grace period for users to update their workflows
|
|
- **Deprecated**: Old unprefixed commands have been removed
|
|
|
|
## Backward Compatibility
|
|
|
|
### Bash Aliases
|
|
|
|
To ease the transition, we provide bash aliases that maintain the old command patterns:
|
|
|
|
```bash
|
|
# Source the aliases file
|
|
source aliases.sh
|
|
|
|
# Or add to your ~/.bashrc
|
|
echo "source $(pwd)/aliases.sh" >> ~/.bashrc
|
|
```
|
|
|
|
Available aliases:
|
|
- `markitect-ingest` → `markitect md-ingest`
|
|
- `markitect-get` → `markitect md-get`
|
|
- `markitect-list` → `markitect md-list`
|
|
|
|
### Convenience Aliases
|
|
|
|
Additional convenience aliases for common usage patterns:
|
|
- `md-ingest-verbose` → `markitect md-ingest --verbose`
|
|
- `md-get-output` → `markitect md-get --output`
|
|
- `md-list-json` → `markitect md-list --format json`
|
|
- `md-list-yaml` → `markitect md-list --format yaml`
|
|
- `md-list-table` → `markitect md-list --format table`
|
|
- `md-list-names` → `markitect md-list --names-only`
|
|
|
|
### Convenience Functions
|
|
|
|
The aliases file also includes useful functions:
|
|
- `md-process-dir <directory>` - Process all .md files in a directory
|
|
- `md-export-all [output-dir]` - Export all stored files to a directory
|
|
- `md-aliases` - Show available aliases and functions
|
|
|
|
## Architecture Benefits
|
|
|
|
This migration brings several benefits:
|
|
|
|
1. **Consistency**: All commands now follow the same prefix pattern
|
|
2. **Plugin Architecture**: Markdown commands are now implemented as a plugin
|
|
3. **Modularity**: Clear separation of markdown functionality
|
|
4. **Extensibility**: Easy to add new markdown variants or processors
|
|
5. **Maintainability**: Better code organization and lazy loading
|
|
|
|
## Implementation Details
|
|
|
|
### Plugin Structure
|
|
|
|
The new commands are implemented in `/markitect/plugins/builtin/markdown_commands.py` as a CommandPlugin:
|
|
|
|
```python
|
|
@register_plugin("markdown_commands")
|
|
class MarkdownCommandsPlugin(CommandPlugin):
|
|
def get_commands(self) -> Dict[str, Any]:
|
|
return {
|
|
'md-ingest': self.md_ingest,
|
|
'md-get': self.md_get,
|
|
'md-list': self.md_list
|
|
}
|
|
```
|
|
|
|
### CLI Integration
|
|
|
|
The plugin is automatically loaded and registered in the CLI:
|
|
|
|
```python
|
|
# Register markdown commands plugin
|
|
try:
|
|
from .plugins.builtin.markdown_commands import MarkdownCommandsPlugin
|
|
plugin_instance = MarkdownCommandsPlugin()
|
|
plugin_instance.initialize()
|
|
for command_name, command_func in plugin_instance.get_commands().items():
|
|
cli.add_command(command_func, name=command_name)
|
|
except ImportError:
|
|
pass # Plugin not available
|
|
```
|
|
|
|
## Migration Checklist
|
|
|
|
- [ ] Update scripts to use `md-` prefixed commands
|
|
- [ ] Source `aliases.sh` for temporary compatibility
|
|
- [ ] Test workflows with new commands
|
|
- [ ] Update documentation and examples
|
|
- [ ] Remove dependency on old command names
|
|
|
|
## Support
|
|
|
|
If you encounter issues during migration:
|
|
|
|
1. Check that you're using the latest version
|
|
2. Source the `aliases.sh` file for temporary compatibility
|
|
3. Report issues at the project repository
|
|
4. Consult this migration guide
|
|
|
|
The new plugin architecture provides a solid foundation for future enhancements while maintaining the core functionality users depend on. |