• 📜 Mayr Markdown CMS
  • 🌟 Features
  • 🚀 Getting started
  • 🚀 Usage
    • 1. Import the Package
    • 2. Fetch and Display Content
      • From Local Asset:
      • From Network URL:
      • Using a Custom Future:
    • 3. Internal Actions on Links
    • 4. Extend the Package
  • 🛠️ Configuration
  • 📢 Additional Information
    • 🤝 Contributing
    • 🐛 Reporting Issues
    • 📜 Licence
  • 🌟 Support

📜 Mayr Markdown CMS #

Fetch, Load, and Render Markdown — the Smart Way.

mayr_md_cms is a powerful yet lightweight Flutter widget for fetching and displaying Markdown content from multiple sources:

• Local asset files 📂
• Network URLs 🌐
• Custom-defined futures ⚡

With built-in loading indicators, error handling, and smooth Markdown rendering, mayr_md_cms saves you from boilerplate and keeps your UI clean.

Whether you are building a blog, documentation app, or a CMS-driven mobile app, mayr_md_cms makes working with Markdown effortless!

🌟 Features #

• Fetch and Render Markdown: Seamlessly fetch and display Markdown content from various sources like local assets, network URLs, or custom futures.

• Automatic Link Handling: Automatically handle link clicks within the Markdown:

  • Open valid URLs in the browser 🌐

  • Copy to clipboard for invalid links 📋

  • Option to let users define their custom link handling 🛠️

• Internal Link actions: Add custom internal links in your Markdown (e.g., [About Us](internal:about_us)), and map them to custom actions (e.g., {'internal:about_us': (context) {...}}). Clicking such links will run the custom actions provided

• Fully Customisable:

  • Modify the loading widget 🌀

  • Customise the error widget ⚠️

  • Change the Markdown stylesheet (colors, fonts, etc.) 🎨

• Extendable: Create your own custom Markdown CMS by extending the base class:

  class CustomMdCms extends MayrMdCmsBase {
    @override
    MayrMdCmsConfig get config => MayrMdCmsConfig(...);
  }
  

  Define your own custom behavior, UI components, and logic.

• Built-in Loading and Error Handling: Graceful fallbacks for loading content and error states 🛠️

• Flexible Content Source: Fetch content from various sources like:

  • Local assets using fromLocal()

  • Network URLs using fromNetwork()

  • Custom async functions using custom()

🚀 Getting started #

1. Add mayr_md_cms to your pubspec.yaml:

   dependencies:
       mayr_md_cms: # check for the latest version on pub.flutter-io.cn
   

2. Install the package:

   flutter pub get
   

3. Import it into your Dart file:

   import 'package:mayr_md_cms/mayr_md_cms.dart';
   

   Alternatively, you could install it using the command:

   flutter pub add mayr_md_cms
   

🚀 Usage #

Here’s how to use MayrMdCms and display Markdown content in your Flutter app:

1. Import the Package #

Import the package into your Dart file:

import 'package:mayr_md_cms/mayr_md_cms.dart';

2. Fetch and Display Content #

From Local Asset:

If you have a Markdown file in your assets:

MayrMdCms.local(
  'assets/content.md',
  config: mayrMdCmsConfig, // Config is optional
);

// More on the config later

From Network URL:

If you want to fetch the Markdown content from a URL:

MayrMdCms.network(
  'https://example.com/content.md',
  config: mayrMdCmsConfig, // Config is optional
  dioClient: dioClient, // Optional
);

// You could choose to pass your own instance of dio that would be used in getting the page.
// This is useful if for example authentication is required to access the page or extra dio configurations are needed

Using a Custom Future:

You can also pass a custom Future to fetch content, giving you full control over the data source:

MayrMdCms.custom(() async {
  // Custom async fetch logic
  return 'Your custom markdown content goes here';
});

3. Internal Actions on Links #

To create internal navigation in your app, define internal links in your Markdown (e.g., [About Us](internal:about_us)), and map them to your custom widgets:

Internal actions and handlers can be used as below:

1. Define your internal actions on the config:

   MayrMdCms.network(
     'https://example.com/content.md',
     config: MayrMdCmsConfig(
       internalActions: {
         "internal:action_one": (context) => print("Link One clicked"),
         "internal:action_two": (context) => print("Link two clicked"),
       },
     ),
   );
   

2. Add the links to your markdown

   You could choose to perform [Action One](internal:action_one) or even [Action Two](internal:action_two)
   

Now when user clicks on any of the action links, the associated actions would be run

4. Extend the Package #

For more control, you can create a custom class that extends MayrMdCmsBase and override methods or add new logic:

class CustomMdCms extends MayrMdCmsBase {
  @override
  MayrMdCmsConfig get config => MayrMdCmsConfig(
    loadingWidget: MyCustomLoadingWidget(),
    errorWidget: MyCustomErrorWidget(),
    emptyWidget: MyCustomEmptyWidget(),
    shrinkWrap: true,
    scrollPhysics: const NeverScrollableScrollPhysics(),
    internalActions: {
      "internal:indicate_interest": (context) {...},
      "internal:go_to_signup": (context) => Navigator.pushNamed(context, "/signup"),
      "internal:switch_theme_dark": (context) => MyThemeSwitcher.toDark(),
    },
    markdownStyleSheet: MyCustomMarkdownStyleSheet(),
  );
}

After the package has been extended, it can then be used as below:

CustomMdCms().local('assets/content.md');
CustomMdCms().network('https://example.com/content.md');
CustomMdCms().custom(() async => '# Custom Content');

🛠️ Configuration #

Certain aspects of the package can be configured using the MayrMdCmsConfig(...) class. A sample configuration is:

MayrMdCmsConfig(
  loadingWidget: MyCustomLoadingWidget(),
  errorWidget: MyCustomErrorWidget(),
  emptyWidget: MyCustomEmptyWidget(),
  shrinkWrap: true,
  scrollPhysics: const NeverScrollableScrollPhysics(),
  internalActions: {
    "internal:indicate_interest": (context) {...},
    "internal:go_to_signup": (context) => Navigator.pushNamed(context, "/signup"),
    "internal:switch_theme_dark": (context) => MyThemeSwitcher.toDark(),
  },
  markdownStyleSheet: MyCustomMarkdownStyleSheet(),
)

📢 Additional Information #

🤝 Contributing #

Contributions are highly welcome! If you have ideas for new extensions, improvements, or fixes, feel free to fork the repository and submit a pull request.

Please make sure to:

• Follow the existing coding style.
• Write tests for new features.
• Update documentation if necessary.

Let's build something amazing together!

🐛 Reporting Issues #

If you encounter a bug, unexpected behaviour, or have feature requests:

• Open an issue on the repository.
• Provide a clear description and steps to reproduce (if it's a bug).
• Suggest improvements if you have any ideas.

Your feedback helps make the package better for everyone!

📜 Licence #

This package is licensed under the MIT License — which means you are free to use it for commercial and non-commercial projects, with proper attribution.

See the LICENSE file for more details.

🌟 Support #

If you find this package helpful, please consider giving it a ⭐️ on GitHub — it motivates and helps the project grow!

You can also support by:

• Sharing the package with your friends, colleagues, and tech communities.
• Using it in your projects and giving feedback.
• Contributing new ideas, features, or improvements.

Every little bit of support counts! 🚀💙