Bring docsify-cli into this repo for easier development.

[trusktr]

Also archive the docsify-cli repo after.

[jhildenbiddle]

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

• A site generator This seems like it could replaced with a GitHub repo intended to be "cloned as template" (which would provide a far easier process for getting a new site online using GitHub), an 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?
• A sidebar generator This is the most interesting feature of 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.

[sy-records]

I agree with @jhildenbiddle. Keep docsify-cli as the standalone repository it is now.

[trusktr]

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

• static site generation (eventually) where we output the site as all HTML (this does not compile Markdown on client side)
  • How can this be replaced by a GitHub template? How will that handle Docsify plugins and generate HTML?
  • Managing an npm-init package isn't very different than managing a CLI. They're both a CLI, in different formats, and that code will have to go somewhere, and I propose the main repo for easy maintenance (we've limited free time)
• search index generation. Right now Docsify tries to discover your files dynamically, with lots of failed requests, and it can't always discover your files if you have separate sidebars (basically the feature is kinda broken for people who don't know how it works and introduce multiple sidebars)

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

• commits that are aligned and no surprises
• everything tested all in one together.

Right now, it is possible to change Docsify in some way that breaks the CLI, and we won't know this happened.

[jhildenbiddle]

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. :)

[trusktr]

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:

• move cli into repo, keep it in sync (delete it later if we decide to, explore other ideas later if we decide to)
• delete it now (or archive it) (explore other ideas later if we decide to)

In other words, choosing between:

• keep it working in the simplest way possible
• or acknowledge we don't want to maintain it as-is, and deprecate it right now (instead of the messy option of leaving it as-is and people potentially being interested in it and then finding problems and being disappointed)

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:

• search plugin fixes
  • remove code characters from search results (f.e. use textContent instead of innerHTML, or something), it harms readability a lot
• search index generation, with option to turn off the flaky client-side search index generation
• SEO (this might include a new SSG concept that I'll make in a fork, using a framework like Astro or similar designed for this purpose)

[trusktr]

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.

[jhildenbiddle]

@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:

• Updated dependencies and corresponding code changes. For example, docsify-cli uses rollup v1 while docsify uses v3, therefore the cli's rollup configuration should be updated to work with rollup v3 so the repo utilizes on version of rollup.
• Removal of outdated / unnecessary dependencies and code. For example, SSR-related code and dependencies should be removed from the CLI tool to continue the work from #2105.
• Isolation of tests per environment (e.g., don't mix docsify-cli's Ava-based e2e tests with docsify's Playwright-based e2e tests).
• A deprecation warning added to the docsify-cli repo to notify users with local installs (per our Quick Start guide) that updates will no longer be available along with migration instructions
• Updates to the Quick Start page and other sections mentioning docsify-cli (e.g. the Docker deployment instructions)
• CLI documentation available on https://docsify.js.org
• https://cli.docsifyjs.org redirected to https://docsify.js.org

If we are conscientious about how we merge as outlined above, I'm all for it.

[Koooooo-7]

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:

1. Help to generate template with mentioned plugins .
2. Generated docsify styles files based on other format files, such as sidebar auto generator.
3. Migration other docs from other doc system/software to docsify.
4. Auto generator configs on specific server deployment.

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.

[Koooooo-7]

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.