docs icon indicating copy to clipboard operation
docs copied to clipboard

FR: A central place to style all Feathers docs.

Open DaddyWarbucks opened this issue 3 years ago • 0 comments

I recently created https://github.com/DaddyWarbucks/remote-docsify as a quick little POC as I was working on docs for the V2 of feathers-dataloader (currently known as feathers-batchloader). This repo uses Docsify to add styling, search, navigation, etc to .md files. But, it takes all of the Docsify config via URL parameters.

  • The Problem - Feathers has a plethora of supporting libraries in feathers-ecosystem and other places. Some of these repos uses basic .md files for documentation, and others may use a more robust solution like Vuepress. For those repos that do not use some documentation solution, the docs are bland and not searchable.

  • The solution - Add/fork/transfer the remote-docsify repo and github page to this repo (or perhaps in feathers-ecosystem is a better place?), Then update any and all feathers supporting repos to have the proper link to style their documentation. This offers a cohesive developer experience for all Feathers repos including similar styling, search capabilities, navigation, etc.

Please see the following links for examples:

Feathers Sequelize: https://daddywarbucks.github.io/remote-docsify/?basePath=https://raw.githubusercontent.com/feathersjs-ecosystem/feathers-sequelize/master#/

Feathers MongoDB: https://daddywarbucks.github.io/remote-docsify/?basePath=https://raw.githubusercontent.com/feathersjs-ecosystem/feathers-mongodb/master#/

There was no change to those two repos, the only thing done was to create a link like https://daddywarbucks.github.io/remote-docsify/?basePath=...the path to raw github. This means that there is no need to config, setup, fight with a documentation builder per repo. The remote-docsify (which could obviously be renamed) just basically consumes whatever markdown files are in a repo and "Feathers-ifys" them.

To accomplish this, we would need to host this remote-docsify repo and github page somewhere more permanent than my own DaddyWarbucks account, and then update any repo that wants to use it's README with something like

[View the detailed documentation](...?basePath=...)

You can also checkout this issue in the Docsify repo where I proposed that Docsify offer this as a solution themselves: https://github.com/docsifyjs/docsify/issues/1789

DaddyWarbucks avatar Apr 20 '22 18:04 DaddyWarbucks