MDLess (MDL) - Visual Studio Code Extension
Table of Contents
- Overview
- Features
- Usage
- Media Embedding
- Dynamic Table Creator
- Interactive Date Picker
- Customization and Theming
- Technical Details
- Advanced Syntax Highlighting
- Extended Examples
- FAQs
- Changelog
- Roadmap
- Contributing
- License
- Contact and Support
Overview
MDLess (MDL) is an advanced markdown-like language built specifically for Visual Studio Code. It extends standard Markdown with a robust set of features designed to make document creation interactive and visually appealing. With MDLess, you can integrate dynamic content, customize document styles, and embed multimedia elements effortlessly—all without the need for complex HTML.
MDLess was designed with both simplicity and power in mind. Whether you're a developer, writer, or content creator, MDLess equips you with tools that elevate your documents into dynamic, interactive works of art.
Features
- Full Customization: Tweak colors, fonts, and themes to suit your style.
- Enhanced Note System: Create notes with multiple styles such as
tip, warning, danger, and info to emphasize key points.
- Media Embedding: Easily embed tweets, YouTube videos, standard videos, and more with simple, intuitive tags.
- Dynamic Element Positioning: Place elements in your document using structured tags—no HTML required.
- Advanced Syntax Highlighting: Enjoy improved code block rendering and dynamic styling.
- Dynamic Table Creator: Generate Markdown tables by simply typing commands like
tableNxM (e.g., table5x5).
- Interactive Date Picker: Type
setdate to open a webview for selecting dates, which are then inserted in ISO format.
Usage
After installing MDLess, the extension automatically enhances syntax highlighting and supports additional functionalities for files with the .mdl extension in Visual Studio Code.
Getting Started
- Install MDLess from the Visual Studio Code Marketplace.
- Open any
.mdl file in Visual Studio Code.
- Begin writing using the enhanced MDLess syntax.
Example: Creating a Note
You can create a styled note by using the following syntax:
{{note:This is an example note to highlight important information.},{type:tip}}
OUTPUT:
{{note:This is an example note to highlight important information.},{type:success}}
OUTPUT:
Replace tip with warning, danger, or info to change the note style.
MDLess allows you to easily embed multimedia content. Use the following tags to integrate various types of media:
To embed a tweet, use the tweet tag along with the tweet ID:
{{tweet:1896428531015676278}}
OUTPUT:
This tag dynamically fetches and renders the tweet within your document.
Embedding a YouTube Video
Embed a YouTube video by using the youtube tag with the video ID:
{{youtube:B9xVYpuYMm8}}
This will insert the YouTube video player directly into your Markdown file.
Embedding a Standard Video
To embed a video hosted elsewhere, use the video tag with the full URL:
{{video:https://gitlab.com/-/project/67652609/uploads/502303c986fff38beba4fd51f700ef19/istockphoto-2101326807-640_adpp_is.mp4},{size:20%,10%},{position:start}}
OUTPUT:
Embedding a Standard Image
To embed a image hosted elsewhere, use the image tag with the full URL:
{{image:[https://gitlab.com/-/project/67652609/uploads/502303c986fff38beba4fd51f700ef19/istockphoto-2101326807-640_adpp_is.mp4](https://gitlab.com/less24/mdless/raw/main/assets/logo.png)},{size:50%,100%},{position:end}}
OUTPUT:
Dynamic Table Creator
MDLess includes a dynamic table creation feature that turns simple commands into fully formatted Markdown tables.
How It Works
- Command Syntax: Type
tableNxM where N is the number of rows and M is the number of columns.
- Example: Typing
table5x5 in your document will automatically generate a 5x5 Markdown table.
Detailed Example
table6x4
OUTPUT:
The above command creates a table with 4 rows and 3 columns. You can then customize the headers and cell content as needed.
Interactive Date Picker
The interactive date picker allows you to insert the current date by simply typing setdate.
How to Use
- Type
setdate in your document.
- A webview opens, allowing you to select a date and time.
- Once selected, the date is inserted at the cursor in ISO format.
Example Usage
setdate
After using the date picker, the setdate command is replaced with the chosen ISO date string.
Customization and Theming
MDLess offers extensive customization options to help you tailor the look and feel of your documents.
Customization Options
- Colors: Modify the color scheme for notes, tables, and general text.
- Fonts: Choose from various fonts and adjust sizes.
- Themes: Easily switch between light and dark themes.
- Highlighting: Customize syntax highlighting rules to enhance code readability.
How to Customize
You can adjust these settings through Visual Studio Code's settings menu or by editing the MDLess configuration file. Detailed documentation is available for each customization option.
Technical Details
MDLess is built using the Visual Studio Code extension API and structured into several modular components.
Project Structure
- extension.ts: Main entry point for activating all features.
- Features Folder:
tableCreator.ts: Manages dynamic table generation.datePicker.ts: Handles the interactive date picker.highlighter.ts: Applies advanced syntax highlighting and dynamic styling.
- Test Folder: Contains tests ensuring the robustness and reliability of MDLess.
How It Works
- Activation: MDLess is activated when a
.mdl file is opened or edited.
- Event Listeners: The extension listens for specific commands like
tableNxM and setdate.
- Webview Integration: The date picker uses a webview to provide an interactive interface for date selection.
Advanced Syntax Highlighting
The highlighter component in MDLess enhances the document by applying rich syntax highlighting to code blocks and custom tags.
Supported Languages
- JavaScript, TypeScript, Python, HTML, CSS, and many more.
- Custom rules for MDLess-specific syntax elements ensure consistency and clarity.
Benefits
- Improved Readability: Enhanced code blocks make it easier to read and understand your code.
- Dynamic Updates: Any changes to your document immediately trigger re-highlighting.
Extended Examples
Below are some comprehensive examples that demonstrate the full capabilities of MDLess.
Example 1: Comprehensive Document with Mixed Elements
Create a document that incorporates notes, media, dynamic tables, and date pickers.
# Document Title: My MDLess Document
{{note:Remember to review the documentation for the latest updates.,{type:info}}}
Embedded Tweet Example:
{{tweet:1897017974978224169}}
YouTube Video Example:
{{youtube:B9xVYpuYMm8}}
Dynamic Table Generation:
table4x3
Interactive Date Picker:
setdate
Thank you for using MDLess!
Combine different media elements into one cohesive document.
{{note:This is a warning note. Use caution when editing critical data.,{type:warning}}}
Standard Video Embed:
{{video:https://example.com/media/video.mp4},{size:100%,50%},{position:end}}
Another Tweet Embed:
{{tweet:9876543210987654321}}
Additional YouTube Clip:
{{youtube:3JZ_D3ELwOQ}}
Example 3: Developer Documentation Template
An example for developers to document processes using MDLess.
# Developer Documentation
{{note:Developer Note: Ensure that all code is thoroughly tested.,{type:danger}}}
Project Metrics Table:
table7x6
Embedded Tweet for Updates:
{{tweet:1234567890123456789}}
Tutorial Video:
{{youtube:B9xVYpuYMm8}}
Project Start Date:
setdate
End of Documentation.
FAQs
Q1: What file extension does MDLess use?
MDLess is designed for files with the .mdl extension.
Q2: Can I mix standard Markdown with MDLess?
Absolutely. MDLess is fully compatible with standard Markdown, allowing you to blend both syntaxes seamlessly.
Q3: How do I update MDLess?
Updates are provided through the Visual Studio Code Marketplace. Regularly check for updates or visit the GitLab repository.
Q4: What should I do if a feature isn’t working?
Review the troubleshooting section below and consult the GitLab issues for solutions. You may also contact the maintainer for assistance.
Q5: Can I contribute to MDLess?
Yes, contributions are welcome! Please refer to the Contributing section for more details.
Troubleshooting
- Syntax Highlighting Issues: Ensure your file has the correct
.mdl extension.
- Table Generation Problems: Verify that your command follows the format
tableNxM (e.g., table5x5).
- Date Picker Not Activating: Confirm that you typed
setdate exactly.
- Media Embedding Failures: Double-check that the media ID or URL is valid.
Changelog
Version 0.1.5
- Initial release with core features:
- Enhanced note system with multiple styles.
- Dynamic table creator.
- Interactive date picker.
- Advanced syntax highlighting.
- Media embedding for tweets, YouTube, and standard videos.
Version 0.1.4
- Improved customization options.
- Bug fixes and performance improvements.
- Added support for additional media types.
Version 0.1.3
- Beta release with foundational MDLess functionalities.
- Introduced dynamic element positioning and note styling.
Roadmap
Future enhancements for MDLess include:
- Expanded Media Support: Integration with more social media platforms (e.g., Instagram, TikTok).
- Enhanced Customization: More theme options and refined styling capabilities.
- Real-Time Collaboration: Features to support multi-user editing.
- Additional Tags: New commands and components to enrich content.
- Performance Optimization: Continuous improvements for speed and responsiveness.
- User Feedback Integration: Incorporate community suggestions into future releases.
Contributing
We welcome community contributions! To contribute:
- Fork the repository.
- Create a feature or bugfix branch.
- Commit your changes with clear commit messages.
- Open a pull request describing your changes.
- Participate in code reviews and discussions.
Contribution Guidelines
- Adhere to the established coding standards.
- Write unit tests for new features.
- Update documentation as necessary.
- Respect the community guidelines in all interactions.
License
MDLess is licensed under the MIT License. See the LICENSE file for full details.
For issues, questions, or feedback:
Detailed Tag Usage
Notes
- Syntax:
{{note:Your message here, {type:style}}}
- Styles:
tip: Helpful hints.warning: Cautionary messages.danger: Critical alerts.info: Informational messages.
- Example:
{{note:This is a tip note. Use it to highlight key information.,{type:tip}}}
- Syntax:
{{tweet:TweetID}}
- Example:
{{tweet:1897017974978224169}}
- Note: Ensure the tweet ID is valid. The extension dynamically fetches and renders the tweet.
YouTube Video Embedding
- Syntax:
{{youtube:VideoID}}
- Example:
{{youtube:B9xVYpuYMm8}}
- Note: Extract the video ID from the YouTube URL (e.g., in
https://www.youtube.com/watch?v=B9xVYpuYMm8, the ID is B9xVYpuYMm8).
Standard Video Embedding
- Syntax:
{{video:URL}}
- Example:
{{video:https://example.com/videos/sample.mp4},{size:500px,100%},{position:center}}
- Note: Use a direct URL to the video file.
Dynamic Table Creator Command
- Syntax:
tableNxM
- Example:
table6x4
- Description: Generates a table with 6 rows and 4 columns.
- Usage: Edit the generated table to customize headers and content.
Date Picker Trigger
setdate
- Description: Opens a webview to select a date and time, which is then inserted in ISO format.
- Usage: Simply type
setdate and follow the prompts.
More Examples and Use Cases
Combine notes, media embeds, tables, and a date picker:
# Title: Mixed Media Example
{{note:Welcome to the mixed media example. This document demonstrates multiple MDLess features.,{type:info}}}
Embedded Tweet:
{{tweet:1897017974978224169}}
YouTube Video:
{{youtube:B9xVYpuYMm8}}
Dynamic Table:
table3x3
Date Picker:
setdate
Thank you for exploring MDLess!
Developer Documentation Example
A template for developers documenting code and processes:
# Developer Documentation
{{note:Developer Note: Ensure all new code is well-tested.,{type:warning}}}
Project Metrics Table:
table4x5
Embedded Tweet for Updates:
{{tweet:1234567890123456789}}
Tutorial Video:
{{youtube:3JZ_D3ELwOQ}}
Project Start Date:
setdate
End of Documentation.
Tips for Effective Use
- Always preview your document in VS Code to verify that dynamic elements render correctly.
- Use the provided examples as templates for your own projects.
- Experiment with various note styles and media embeds.
- Keep your MDLess extension up-to-date to benefit from new features and fixes.
Extended Troubleshooting
- Rendering Issues: If media elements do not display correctly, double-check the IDs or URLs.
- Performance Concerns: Large documents may take a moment to update dynamic elements.
- Command Conflicts: Ensure no other extensions conflict with MDLess by temporarily disabling similar tools.
- Community Help: Consult the GitLab repository and community forums for additional troubleshooting tips.
Developer Insights
- MDLess is developed using TypeScript and the Visual Studio Code API.
- Its modular architecture allows for easy addition of new features.
- Code reviews and community contributions help maintain high quality.
- Detailed inline comments in the source code explain each function and feature.
Future Improvements
- New Media Integrations: Support for platforms like Instagram and TikTok.
- Enhanced Theming Options: More themes and customization for a personalized experience.
- Real-Time Collaboration: Features to support simultaneous editing by multiple users.
- Extended API: More commands and customizable tags for richer document creation.
- Performance Enhancements: Ongoing optimizations for large-scale documents.
- User-Driven Updates: Incorporating feedback from the MDLess community.
Additional Resources
Community and Support
- Join the MDLess community on GitLab for discussions and feature requests.
- Participate in forums and contribute to improving MDLess.
- Stay updated by following MDLess on social media and the Visual Studio Marketplace.
Final Notes
MDLess is an evolving tool designed to enhance your document creation experience. Your feedback is crucial for its continuous improvement. Enjoy using MDLess to create dynamic, interactive, and visually appealing documents!
