[2.x] Dynamic Markdown links

[caendesilva]

Dynamic Markdown Links

PR Abstract

Based on RFC 1590 proposed in https://twitter.com/CodeWithCaen/status/1761810371063497098

Overview

HydePHP provides a powerful feature for automatically converting Markdown links to source files to the corresponding routes in the built site.

This allows for much better writing experience when using an IDE, as you can easily navigate to the source file by clicking on the link.

Usage

Using the feature is simple: Just use source file paths for links:

[Home](/_pages/index.blade.php)
![Logo](/_media/logo.svg)

As you can see, it works for both pages and media assets. The leading slash is optional and will be ignored by Hyde, but including it often gives better IDE support.

Behind the Scenes

During the build process, HydePHP converts source paths to their corresponding routes, and evaluates them depending on the page being rendered.

If your page is in the site root then:

• /_pages/index.blade.php becomes index.html
• /_media/logo.svg becomes media/logo.svg

If your page is in a subdirectory then:

• /_pages/index.blade.php becomes ../index.html
• /_media/logo.svg becomes ../media/logo.svg

Of course, if your page is in a more deeply nested directory, the number of ../ will increase accordingly.

We will of course also match your configured preference for pretty_urls and only include the .html extension when desired.

Limitations

There are some limitations and considerations to keep in mind when using this feature:

• This feature won't work for dynamic routes (not backed by a file)
• If you rename a file, links will break. Your IDE may warn about this.
• If a file is not found, we won't be able to see it when evaluating links.
• Relative links are not supported (so ../_pages/index.blade.php won't work)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (2df0527) to head (2ae3ef9).

Additional details and impacted files

@@             Coverage Diff             @@
##             2.x-dev     #1590   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
- Complexity      1866      1876   +10     
===========================================
  Files            191       192    +1     
  Lines           4924      4954   +30     
===========================================
+ Hits            4924      4954   +30     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[caendesilva]

ChatGPT Response to RFC Proposal: Dynamic Markdown Links in HydePHP

---

Benefits:

1. Convenience and Flexibility: The proposed dynamic Markdown links offer a convenient way to create links and embed media assets within pages and posts without worrying about the underlying URL structure. This convenience enhances the developer experience, aligning with HydePHP's goal of convention over configuration.

2. Compatibility: By integrating link resolution into the Markdown processor, Hyde ensures compatibility across different rendering modes, whether it's standard Markdown, custom HTML, or Blade templates. This feature promotes consistency and simplifies the development process.

3. Intuitiveness: The syntax options presented in the RFC prioritize intuitiveness, allowing developers to quickly grasp and utilize dynamic linking capabilities. This aligns well with Hyde's principle of least astonishment, fostering a smooth learning curve for new users.

---

Drawbacks:

1. Syntax Ambiguity: While intuitiveness is a primary concern, it's crucial to avoid ambiguity in syntax. Some proposed alternatives may introduce ambiguity, potentially leading to unexpected behavior or errors. Careful consideration is needed to strike a balance between simplicity and clarity.

2. Potential for Overhead: Depending on the implementation, there might be additional overhead involved in resolving dynamic links during Markdown processing. This overhead could impact performance, especially in scenarios with a large number of links or complex routing configurations.

---

Syntax Improvement:

Considering the DX goals of HydePHP, the syntax should prioritize clarity, conciseness, and unambiguousness. While all proposed syntaxes have their merits, Syntax 1 appears to strike the best balance between these criteria:

[Home](hyde::route('home'))
![Image](hyde::media('image.png'))

This syntax maintains clarity by clearly delineating Hyde-specific functionality (hyde::) while also being concise and intuitive. It's easily memorable and aligns well with existing conventions in the HydePHP ecosystem.

---

Recommendation:

Given the benefits of dynamic Markdown links in enhancing developer experience and content management capabilities, along with the proposed syntax improvement, it's recommended to proceed with the RFC for implementation. However, it's crucial to address potential ambiguities and assess any performance implications during the implementation phase. Additionally, thorough documentation and examples should accompany the feature to assist users in understanding and leveraging its full potential.

---

In conclusion, the proposed dynamic Markdown links feature aligns well with HydePHP's goals and offers significant advantages in content management. With careful attention to syntax clarity and performance considerations, integrating this functionality would be a valuable addition to HydePHP's feature set.

[caendesilva]

Looking back at this, using my favourite syntax: [Home](hyde::route('home'))

• Pro: Can link to dynamic routes
• Pro: Syntax matches the PHP Hyde facade
• Pro: Cannot think of any security vulnerabilities, as it will only resolve existing routes to the local application
• Con: Decreased portability (won't work when migrating to other SSGs, or viewing on GitHub)
• Con: Increased complexity
• Con: New syntax to remember

[caendesilva]

Switching to rebase and target v2 due to v1 feature freeze #1877