Hosted Docsify

[DaddyWarbucks]

Feature request

What problem does this feature solve?

This feature solves the problem of the developer having to deploy and host the index.html file ourselves. As a developer, I don't want to have to setup and host (via Github Pages or anywhere else) the static HTML file that Docsify runs on. Instead I would prefer a freemium solution that allows me to leverage an HTML page that is hosted by Docsify/Vercel and configured via URL parameters.

What does the proposed API look like?

https://docsify.js.org/preview?config=...docsify config or more simply https://docsify.js.org/preview?basePath=https://github.com/feathersjs-ecosystem/batch-loader/tree/v2/docs

How should this be implemented in your opinion?

• Docsify/Vercel would host a static HTML page. For example https://docsify.js.org/preview.
• On page load, some javascript would extract the Docsify config from the URL using something like qs or querystring preferably to more easily allow JSON in the URL, but SearchParams could also be used.
• The config extracted from the URL is passed to the Docsify init javascript. We could also extend the config to include other items like theme=dark that would dynamically write in the corresponding theme's css.
• Docsify does its thing!

I understand that there are a number of caveats and lack of customization with this approach. The user can't write their own custom CSS, etc. But thats fine IMO. I want a bare-bones, dead-simple solution where I can just include the link in my README and not think about it.

Are you willing to work on this yourself?

Yes. But this more of a business/admin decision I believe. I am capable and willing to write the HTML page and JS to accomplish this.

[paulhibbitts]

This is a pretty interesting FR @DaddyWarbucks - I've been thinking about something like this for the EDU space along the lines of https://github.com/LiaScript/LiaScript, for example https://liascript.github.io/course/?https://raw.githubusercontent.com/liaBooks/C-Programming/master/README.md#1 but that platform only works with a single MD file

[DaddyWarbucks]

Thanks @paulhibbitts.

I built a proof of concept that can be seen here: https://github.com/DaddyWarbucks/remote-docsify

The initial reason I thought about this for the Feathers.js ecosystem. Feathers has a core docs site, but there are a number of other official and non-official repos that could benefit from a shared style and easy docs. So that example defaults to some Feathers styling, name, description, etc. But its dead simple and works.

https://daddywarbucks.github.io/remote-docsify/?basePath=https%3A%2F%2Fraw.githubusercontent.com%2Ffeathersjs-ecosystem%2Ffeathers-sequelize%2Fmaster#/?id=feathers-sequelize

The "magic" is just

window.$docsify = {};
const params = new URLSearchParams(window.location.search);
params.forEach((value, key) => {
  // TODO: Parse numbers?
  window.$docsify[key] = value;
});

[paulhibbitts]

That's pretty amazing @DaddyWarbucks 👍🏼

I've got a few questions🙂

1. Could you please share the GitHub repo URL for the "linked" content?
2. Will this work on a multiple-file content site?
3. A key piece of functionality I use with my Docsify open education/publishing projects is an embedded "Edit on GitHub" link, as shown at https://hibbitts-design.github.io/demo-docsify-open-course-starter-kit/#/ Is something like this still possible in a "hosted" approach?

The reason I am interested in this is it would keep Docsify content repos more streamlined with just content, and allow a customized Docsify setup delivery multiple courses/publications/etc.

UPDATE: As an experiment, I tried REMOTE DOCSIFY with an existing Docsify site https://daddywarbucks.github.io/remote-docsify/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-open-course-starter-kit/main/docs#/ but I cannot seem to get it to work... am I missing something?

I've been able to get it working here on a single ReadMe file, but the site title link seems to not work: https://paulhibbitts.github.io/remote-docsify/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-open-course-starter-kit/main/#/

Would you mind if I used your technique for one of my own Docsify sites @DaddyWarbucks ? I would of course credit you in the index.html file.

Thanks very much! Paul

[DaddyWarbucks]

Of course you are welcome to use it!

1. I am not sure what you mean about the "linked" content? The basePath being used is: https://raw.githubusercontent.com/feathersjs-ecosystem/feathers-sequelize/master So the whole full URL is https://daddywarbucks.github.io/remote-docsify?basePath=https://raw.githubusercontent.com/feathersjs-ecosystem/feathers-sequelize/master

2. It should work with multiple file sites. It should do whatever Docsify can do.

3. If a Docsify config property is serializable to a string, then it can be used in the URL. So I believe you are looking for the repo property. Note in my little code snippet above the // TODO: Parse numbers?. Numbers are strings in a URL, so they may need to be converted back to numbers

I believe your /docs directory has to have a README.md file, which I don't think yours does: https://github.com/hibbitts-design/docsify-open-course-starter-kit/tree/main/docs. I think there is some setting to tell docsify what the "main" file is if its not README.md, so you need to include that in the url. I don't know that parameter name off the top of my head, but assuming it is main you would want ?basePath=https://github.com/hibbitts-design/docsify-open-course-starter-kit/tree/main/docs&main=index.md. Note the &main=index.md

[paulhibbitts]

Thanks so much @DaddyWarbucks ! Thanks also for the info, that all helps. The one thing that still has me stuck is the left-hand site title link on the sidebar. For example, on your example site https://daddywarbucks.github.io/remote-docsify/?basePath=https%3A%2F%2Fraw.githubusercontent.com%2Ffeathersjs-ecosystem%2Ffeathers-sequelize%2Fmaster#/?id=feathers-sequelize if you tap on the "Feathers Docs" hyperlink at the top of the Sidebar you get a "Whoops" page - is that a known issue or something that could be addressed?

[DaddyWarbucks]

Ahhh. Yea. I defaulted some settings to use some Feathers default settings because it was a POC for the Feathers community and my intention was to potentially move it to a more permanent home somewhere in the Feathers ecosystem. It really looks like this

window.$docsify = {
  themeColor: '#d513a5',
  name: 'Feathers Docs',
  description: 'A library for the Feathers framework'
};
const params = new URLSearchParams(window.location.search);
params.forEach((value, key) => {
  // TODO: Parse numbers?
  window.$docsify[key] = value;
});

So you would want to remove/replace those default config properties on your fork.

The "Whoops" page is actually the README from the remote-docsify repo, meaning it is not really part of the docs you are trying to display. But, the site runs on Docsify and Docsify requires a README file to run. So that is basically a fallback if no ?basePath is provided in the URL. But, it looks like if you click on the "Feathers" in the sidebar it redirects to there...I am sure you could pass some default config or URL config that would make that work a different way.

[paulhibbitts]

Thanks so much @DaddyWarbucks for the additional info.

I remain stumped on how to change the Sidebar title homepage link though, I've gone through the Docsify docs and thought this would work:

https://paulhibbitts.github.io/remote-docsify/?basePath=https://raw.githubusercontent.com/hibbitts-design/docsify-open-course-starter-kit/main&homepage=https://raw.githubusercontent.com/hibbitts-design/docsify-open-course-starter-kit/main/README.md

but it does not seem to work. I then hardcoded the following in my index.html file and of course that worked (since removed it): homepage: 'https://raw.githubusercontent.com/hibbitts-design/docsify-open-course-starter-kit/main/README.md',

Any further ideas/suggestions? Your remote Docsify approach is an amazing way to Docsify multiple ReadMe's with one single Docsify site! Thank you.

[paulhibbitts]

Thanks again for this remote Docsify example @DaddyWarbucks! I've now created a collection of my various Docsify ReadMe's using your technique at https://hibbitts-design.github.io/docsify-project-docs/#/ and have credited you in the ReadMe and Index.html file at https://github.com/hibbitts-design/docsify-project-docs.

[paulhibbitts]

Hi @DaddyWarbucks , I thought you might be interested in seeing what has developed so far with your Remote Docsify example🙂 https://docsify-this.net/#/

If you would like any changes to the credit to yourself at the bottom of the page please let me know!