Allow Serving "Virtual" Routes from Plugins
See original GitHub issueFeature request
Plugins are a great way to introduce dynamic content into existing pages. But, what if we took this a step further, and allowed plugins to actually generate the routes themselves on the fly?
The feature I want to contribute introduces an API for plugins to actually provide dynamically generated pages for routes, even if actual markdown files do not exist to begin with.
What problem does this feature solve?
Say that you have a list of APIs, which can change at any time. Each one should have its own page under /apis/<METHOD_NAME>.md
.
Today, you will have to create real markdown files and deploy them along with your site, as every route in a Docsify website requires that a file exist on the server. This means that you will have to create all the /apis/*.md
files manually and deploy them, and do this every time that even a character changes in any of the API descriptions.
With my proposed solution, you will be able to create a plugin that intercepts all fetches from /apis/*
, and provide dynamically generated markdown as replacement from fetching real markdown files from the server.
What does the proposed API look like?
Add a new hook to the Plugin API, called: fetchRoute(cb)
, which will essentially allow plugins to intercept fetch requests before they are made by the underlying engine. If any plugin has a fetchRoute hook, and the callback provided any content for the route, use that content instead of fetching.
The fetchRoute Hook Behavior
This hook receives a callback, possibly async, that implements the following signature: (route: Route, next: fn) => void | Promise<void>
. The route object is the same one that can be found on vm.route
.
The next
function can either receive a markdown
string, or nothing at all. If a non-empty string was provided, then this is the markdown that will be passed into the system, and no fetch
will be done by the Fetch class itself.
If the next
function was called with a falsy value, it will just call the next plugin that has fetchRoute
. Finally, if all plugins were exhausted and none returned any markdown, the internal fetch
function will be run like today.
Flow Diagram
How should this be implemented in your opinion?
From my brief introduction to the code, I would suggest that we edit the _fetch
method (link to code), so instead of directly using get
, it will run the fetchRoute
hooks first and only fall back to get if none return markdown.
Are you willing to work on this yourself?
Yes 😃 Would love to.
Issue Analytics
- State:
- Created 2 years ago
- Reactions:5
- Comments:17 (17 by maintainers)
Top GitHub Comments
Hey! Sorry for the delay, seems like I completely missed the previous update!
This looks like a great idea. Gonna start working on the first PR asap.
Thanks! Working on the PR as we speak.