Open trusktr opened 10 months ago
Is it worth revisiting the need for docsify-cli
?
Based on the docs it provides the following:
A web server
This is handy, butdocsify-cli
also requires Node.js which does not ship with macOS or Windows (it does with many Linux distros though) and isn't something everyone wants or has the ability to install. There are other options available that are either already installed on systems (Python3 http server on macOS and Linux) or just as easily accessed via Node (e.g., http-server via npx
) that we could detail in our documentation:
# Change to site directory
cd /path/to/site
# Python (v3)
python -m http.server
# Node
npx http-server
npm-init
package, or a .zip file available for download from the docsify website. Neither of these alternatives provide the interactive options that docsify-cli
offers, but what's faster: changing stylesheet names and adding/removing plugin <script>
tags which many people will already know how to do or learning which feature flags do what with docsify-cli
?docsify-cli
as far as I can tell. Perhaps we can explore other ways to implement this feature using like an npm-init
package or the File System API (see here for details).I don't have strong feelings one way or the other. I'm only proposing revising the need for docsify-cli
to avoid merging potentially unnecessary code into the main docsify repo.
I agree with @jhildenbiddle. Keep docsify-cli as the standalone repository it is now.
I think @jhildenbiddle is asking if we should even keep the cli or not, regardless where it is located.
Agreed, a static server feature isn't really a high importance feature, but the other things do seem unique and not possible to handle with just a template (but happy to know I'm wrong if there's a way).
Besides sidebar generation, I think we should keep it for future
As for the sidebar generator, I don't see how the File System API can help with that. That's a client side feature, and sidebar generation is not on the client side.
If we keep the CLI, I think moving it to main repo makes maintaining it easier, so we can have
Right now, it is possible to change Docsify in some way that breaks the CLI, and we won't know this happened.
I think @jhildenbiddle is asking if we should even keep the cli or not, regardless where it is located.
Short-term, this is correct.
My intention in asking the question is to avoid unexpected complications that often result from merging one legacy codebase into another and consider potentially better ways to perform the same tasks as docsify-cli
. If docsify-cli
was a critical component of Docsify, I would agree that having a single repo to manage would be a better for multiple reasons. I'm not convinced that this is the case. A lot has changed since docsify-cli
was created.
Long-term, I agree that we may find ourselves longing for a CLI tool to handle new Docsify features. Or, we may not. The examples you've given (SSG and search index generation) are noteworthy, but to my knowledge nobody is working on those features or intends to work on them anytime soon. Therefore, I don't think it makes sense to merge the docsify-cli
repo into the docsify
repo today. If/when work is being done that requires a CLI tool, we can then decide if we want to merge the two repos. We may instead prefer to create a new CLI tool from scratch within the docsify repo. Who knows.
... the other things do seem unique and not possible to handle with just a template (but happy to know I'm wrong if there's a way).
We could provide a tool on our website that is similar to the one offered on sites like prismjs.com. Docsify only has a few plugins and themes, so this wouldn't be too hard to create. We could build it today as a Vue component and launch it as a simple documentation update if we wanted to.
Another option (as mentioned above) is to provide a site template repo that provides the files necessary for a basic Docsify starter site. Our documentation can provide instruction on how to configure the cloned files to be served by GitHub Pages. This is exactly what @paulhibbitts is doing with docsify-open-cource-starter-kit. It's a non-interactive option (meaning users can't select their plugins or themes), but it's a nice option to have for those who may lack the ability or desire to deal with the CLI, Git, etc.
As for the sidebar generator, I don't see how the File System API can help with that. That's a client side feature, and sidebar generation is not on the client side.
Based on the source code it appears the CLI generator simply reads a local directory of files, generates some basic markdown, and then outputs a markdown file to the local disk. These same steps can be done with the File System API (see here for details).
Should we do this? I dunno. I'm only suggesting that it may be worth exploring since being able to do things that previously required a CLI tool without requiring a CLI tool provides benefits like making features available to people who lack the ability or desire to use a CLI tool. There are obviously implementation details to work out and we may learn that using the File System API for this task is a bad idea. I suggested it only as an option to explore.
Right now, it is possible to change Docsify in some way that breaks the CLI, and we won't know this happened.
Understood, but if we provide alternative ways to generate and serve docsify files we won't need docsify-cli
so we won't need to worry about breaking it. :)
We could provide a tool on our website that is similar to the one offered on sites like prismjs.com.
That would be a big project that I won't have time for. Do you?
Another option (as mentioned above) is to provide a site template repo that provides the files necessary for a basic Docsify starter site.
We have https://github.com/docsifyjs/docsify-template
These same steps can be done with the File System API (see here for details).
Are you suggesting a page on docsify.js.org where the user opens a file picker, selects their docsify project folder, then Docsify site gives them a download containing the sidebar that they can save into their project? That could be neat.
I still think a CLI tool is useful. For example someone can generate their sidebar in a GitHub Action when they push their changes.
Understood, but if we provide alternative ways to generate and serve docsify files we won't need
docsify-cli
so we won't need to worry about breaking it. :)
Yeah, but who is going to implement that?
I propose we do one of these:
In other words, choosing between:
i.e. all of our features should be verified to be working. And we should delete features we don't want.
Being stuck in between doesn't feel like a better option.
Your ideas are interesting, but who wants to and has time to implement those right now?
As soon as I circle back from Lume, my priorities will be:
We could keep it in a separate repo, but then perhaps we should add a test that clones it (possibly as a git submodule), and verifies it works, with each Docsify build. The result would be similar that way too.
@trusktr --
Your ideas are interesting, but who wants to and has time to implement those right now?
None of the projects I've mentioned were on my radar, but any or all of them could be if there was enough interest. Other maintainers or contributors may also have interest, which these types of conversations can initiate and gauge. This is the first time these alternative approaches have been discussed so we don't know what the level of interest is or where these discussions will land. That's why they are worth having.
These proposals don't need to be an either/or options. We can have both CLI- and web-based tools that do the same thing for different users. I am not opposed to having a CLI tool. I proposed considering web-based alternatives to our current CLI tool so we might 1) expose features to a larger audience and simplify the process of using them by removing the Node.js requirement, and 2) make the best use of the limited time and resources we have.
But admittedly, we are getting in the weeds on topics other than this specific issue. I can create separate issues for these features so we can have more focused discussions elsewhere.
As far as merging the two repos goes, this is probably as good a time as any to do it since our development branch already contains breaking changes that will require a major version bump and updated documentation.
Since this work is being done under a larger Simplify and modernize Docsify effort, here's what I would hope to see in the PR:
docsify-cli
repo to notify users with local installs (per our Quick Start guide) that updates will no longer be available along with migration instructionsIf we are conscientious about how we merge as outlined above, I'm all for it.
I agree with @jhildenbiddle that we don't need move cli
into our main repo and we may need delay to do some cli
changes since we are developing in docsify so far (kudo to @trusktr ).
And I m same to @trusktr that I think the cli
is necessary.
Currently, TBH, the cli
is simple, maybe our docsify-template
could simply do the same thing.
But I think the cli
has a further things, to be a docsify-kit
.
What I could image less or more:
plugins
.docsify styles
files based on other format files, such as sidebar auto generator.If we don‘t put it in the main repo, we could individually use other dependencies
in the kit easier (no issue in docsify and kit compatibilities,we just expose more hooks in docsify, and we add fetures in kit).
Besides, the whole things above obviously could put in an web-based
tool (a docsify-initializer
) for different kinds users too.
We could keep it in a separate repo, but then perhaps we should add a test that clones it (possibly as a git submodule), and verifies it works, with each Docsify build. The result would be similar that way too.
I don't like the submodule, the sync stuff
is a nightmare...
We may need find a way to do the integration tests
for cli
, such as github-actions
.
Also archive the docsify-cli repo after.