README microservice

[Kikobeats]

I love the idea to get instant documentation from a README file into a git repository.

For example: https://documentup.com/kikobeats/voll

Do you think we can build something similar powered by docsify?

[QingWei-Li]

Currently we can simply configure docsify to load readme by $docsify.basePath. Do you mean that we provide a service like the documentup?

[Kikobeats]

yes, could be awesome have project documenation at one URL with zero (or minimal) configuration 😄

[QingWei-Li]

Cool. But what is the difference with documentup? Do you have any idea?

[Kikobeats]

Look and feel I think

We can build a similar service that make easy customization, like theme:

https://docsify.org/kikobeats/voll?theme=vue

[QingWei-Li]

I looked under the documentup open issues

• multiple pages? jeromegn/DocumentUp#1 about multiple page
• Search jeromegn/DocumentUp#30 about search
• DocumentUp for wiki pages jeromegn/DocumentUp#38 about render wiki pages

These are the features that docsify has already implemented, Maybe we can make these features in the service. Now, we can render README or docs folder or wiki pages. The users can provide configuration files to customize the docsify.

Are you interested? Maybe we can try to do it, but I do not have much time 😂

[Kikobeats]

Highly related, this is a microservice for render markdown.

• https://marked.now.sh
• https://github.com/amio/marked

[anikethsaha]

can anyone summarize the feature? I am not getting exactly whats the feature here. As I noticed this is in v5 roadmap.

[jhildenbiddle]

I believe the idea is that instead of using the docsify cli to generate files (or manually create an index.html per our docs) users can have a fully-working docsify site based on their README.md file by simply visiting a service URL. For example:

https://docsify.js.org/github/USERNAME/REPO?option1=value&option2=value

It’s an interesting idea and I’d love for this service to exist, but there would be a lot of details to think about (configuration, plugins, limitations compared to a “standard” docsify site, server maintenance and costs, etc.) The counter argument is that the reason for this service to exist is to simplify getting a docsify site up and running quickly which we may be able to do other ways (docsify cli, starters, maybe a simpler service that pushes default docsify files into a /docs folder in an existing GitHub repo, etc.)

My vote would be to remove this from the v5 roadmap simply because it’s such a big project. I’d love for this service to exist, but it’s complex enough that I wouldn’t want to make it a blocker for releasing v5. In the meantime, it would be helpful to track all “reduce the time and effort needed to get a docsify site up and running” efforts so we can pitch these as part of v5 and remind maintainers that this is a priority for docsify in general.

[Kikobeats]

I achieved more or less my own issue shipping nicedoc.io.

e.g., https://nicedoc.io/sindresorhus/got

but they are a room for a lot of improvements, so I think a docsify service of this could be very cool

[anikethsaha]

This is certainly a big project. I was thinking if we can make this a separate project may be under this org.
We mainly need some methods to convert the config from URL parameters to docsify config and as far as plugins are concerned, that can be tricky.
Maybe we passing the plugin cdn link to URL parameter and resolving through our method.

that being said, it requires a whole new discussion and probably a new project instead of here.
Not for next major version.
But this is really a good idea, I will give it a shot in near future.

[aemmadi]

@anikethsaha @jhildenbiddle Wouldn't making a new config option for docsify like:

<script>
  window.$docsify = {
    repo: 'docsifyjs/docsify',
    readRepo: true
  };
</script>

Work?

We could check for the readRepo flag first and if it is true can't we fetch the README.md for the project linked in repo using the github api and just render that instead of looking for docs/README.md in the file system?

If something like this is possible we should implement this rather than working on another project where docsify offers a readme service where users can go to:

https://docsify.js.org/github/USERNAME/REPO?option1=value&option2=value

That becomes a bit more complicated.

What are your thoughts on this? I would definitely love to work on either one of the implementations.

[anikethsaha]

actually it would be something like https://nicedoc.io/ . paste the URL of any github project and get the docs

[aemmadi]

actually it would be something like https://nicedoc.io/ . paste the URL of any github project and get the docs

So the plan is to have something like nicedoc but with docsify theme support and plugins?

[anikethsaha]

I am not sure about the theme or plugins, maybe @jhildenbiddle has better thoughts in this.

What I can see is this is mainly an infra project.
Like simply instead of rendering the markdown, render the whole docsify like a project. So like we the project has _sidebar.md in the root then it would work like docsify's sidebar, directory structures, etc. something like that.
Some feature like a download button which will download a docsify project for that repo. change themes.
Would be great to have plugins running as well.
configs being passed as mentioned above by @jhildenbiddle

These are some rough thoughts.

[jhildenbiddle]

Getting a basics service up and running (e.g. point to a URL and load a docsify site with a remote README.md) would be easy to do. But, like most things, the devil is in the details.

• What about options?
• What about plugins?
• What about themes?
• What about versioning?

Services like nicedoc are great, but the fact that they provide none of the above is no accident. We could easily build a service that read remote markdown files and rendered a default docsify site with zero configuration, but I think that's a much less compelling service than one that allows some (ideally, all) of the above. I think we can do it, but I also think the service should be based on v5 and prioritized accordingly.

[paulhibbitts]

An example of this approach is now available with my project https://docsify-this.net, which is open source and can be further customized by others or used as a work example, so closing this issue.