[NEXT] Docsify v5

[anikethsaha]

New Features To be included (see also 5.0! project board)

1. Static HTML Generation (non-blocking)

2. New markdown Helpers (Needs a list to track)

3. Better executable code syntax in MD

4. Docsify-themeable

• From @jhildenbiddle 's comment in https://github.com/docsifyjs/docsify/issues/657#issuecomment-458341229

Docsify currently offers four official themes: vue, buble, dark, and pure. These themes are all more-or-less the same with the exception of a handful of basic style declarations (color, typography, margin/padding, etc). To make development easier, a CSS preprocessor (stylus) is used to compile each theme by combining a shared CSS file with a theme-specific CSS file. Makes sense.

Docsify-themeable takes a similar approach but offers a much more flexible implementation by leveraging CSS custom properties. The end-user pitch is available on the introduction page, but the approach also provides advantages for docsify maintainers: a single block of CSS used for all themes, with each theme comprised of only a flat list of named values (e.g. --sidebar-background: #ccc) instead of blocks of CSS. Legacy support is also available courtesy of css-vars-ponyfill (which I created specifically for docsify-themeable).

5. Starter packs (CLI)

6. Change the pre-processor for css

7. Migrate to webpack

Feedback/Suggestion/Recommending more changes

Feel free to leave feedback, and suggestion for the above features Plus, Leave a comment if you want to add some more features. We can have a discussion about that.

cc @docsifyjs/cli @docsifyjs/contributors @docsifyjs/core

[QingWei-Li]

I can create a fresh PR if a new version starts development.

[anikethsaha]

I can create a fresh PR if a new version starts development.

Coool. I guess that would fit best ! 💯

[alexellis]

I was impressed with the experience and how fast it was to make something useful -> https://docs.inlets.dev/, but I could really use a static generator to create HTML.

That means: getting permalinks and proper folders i..e /tutorials/k8s/that-one and being able to have the site scraped because it's rendering HTML and served from anywhere.

Looking forward to testing out the new release.

[anikethsaha]

Thanks for the heads up 💯

That means: getting permalinks and proper folders i..e /tutorials/k8s/that-one and being able to have the site scraped because it's rendering HTML and served from anywhere.

I do think we have a focus that includes this.

Looking forward to testing out the new release.

Though I cant assure anyone when the work will begin and when it will be ready for release. But we will try to get it ASAP. 👍

[jhildenbiddle]

Happy to dive back in and help with the integration of docsify-themeable. I’m not sure what the timeline or preferred approach is though, so any guidance from the more active maintainers is welcome.

[anikethsaha]

Happy to dive back in and help with the integration of docsify-themeable

Awesome

I’m not sure what the timeline or preferred approach is though

I don't think there is any timeline as of now. about docsify-themeable, I am not familiar with the library so I think we can discuss that in gitter and proceed with your old approach which you planned.

[jhildenbiddle]

Sounds good, @anikethsaha.

[s-pace]

🎉 Do you want use to help you with search? I am part of the docsearch team https://docsearch.algolia.com/

[anikethsaha]

That would be really great to have it as official plugin or external. Let me know how you would like to proceed . !

[s-pace]

Great. We will make sure to have the correct need:

• Server side rendering - Sitemap.xml
• Proper html elements like <article/> to create a basic configuration - Promote it from our plugin page

All of theme will help the SEO too

[anikethsaha]

• Server side rendering - Sitemap.xml

With plugins we cant do this but we can add a section in our docs.

• Proper html elements like <article/> to create a basic configuration - Promote it from our plugin page

it can be with plugin

[s-pace]

What is the default elements used then instead of <article/> ? We would need some steady class otherwise.

[anikethsaha]

the current search bar is placed in sidebar which is placed in aside. You can check the code for current search plugin here.

• Sidebar is in aside with .sidebar class (steady)
• the main content is placed in section.content . (steady)
• Navbar in nav.app-nav.

If you want to keep the search bar in position where the current one is placed, I think that may not be the clear and complete visibility space for the search result.

This is the current search results

so either you can bring our the search result or place the search bar at the top in the navbar .

I think its better to be in navbar and we can take docusaurus@2's sidebar + navbar layout for reference

[anikethsaha]

Also, we will remove the current dark mode button and it will be added through the core in the navbar

[s-pace]

Glad to ear.

We are working on an amazing new discovery experience with the search so stay tuned (Spoiler, @francoischalifour and @shipow are on 🔥) .

I will be happy to help on that and make the process really smooth for Docsify users

[sy-records]

For website SEO, we need Static HTML Generation. 👍🏻

ssr not working, like docsifyjs/docsify-ssr-demo#3 and docsifyjs/docsify-cli#95

[anikethsaha]

It is a candidate for v5.

[jhildenbiddle]

Thoughts regarding helpers added to #413.

(Apologies in advance for the lengthy post.)

[anikethsaha]

There are few issues with static site generation as we support plugins which kind of does a lot (search bar, pagination etc.). without dom, we cant do it. I am thinking of having jsdom to run the plugins in node but still, I think it won't be consistent. Need second thought about it and also feel free to suggest some better solution for this.

[gisforgabriel]

For running search on a static generated site, a library like https://lunrjs.com/ could be a good option.

An index could be created when running docsify-cli and Lunr could power the sidebar search instead.

It would probably not be as performant or sophisticated as DocSearch, but it would offer a "proper" static experience - probably the kind of compromise that people who would be interested in the SSG option would prefer (if they're anything like me 😉).

That said, having third party search as another option would also be cool 👍

[Jacky2]

I don't know if I can display a floating anchor navigation in each markdown file, like gitbook plugin gitbook-plugin-anchor-navigation-ex

[anikethsaha]

@Jacky2 you can do it by creating a plugin. please ask questions in a separate issue or in gitter.

[trusktr]

Is there an issue tracking 3. Better executable code syntax in MD?

[trusktr]

@anikethsaha I converted some of the above into their own issues, so that we can track them in the 5.0 project board. I assigned you to them just so you're aware / triage.

[trusktr]

I updated the issues, and I gave them all labels like PoC Welcome, PR Welcome, needs discussion, etc, to match what we had here. It will be easier to manage it that way, and to have separate conversations in each one while also seeing the respective cards inside the 5.0! project board.

We could copy the shields back over here, but then that's more work to keep in sync. I think it would be best to rely on the labels, for easier sorting in the issue list or inside the project board, etc.

The labels are a nice visual in the project board and issue lists too.

[jhildenbiddle]

Another v5 feature we should consider is tweaking the docisfy plugin architecture to be more resilient. This warrants further discussion, but here are two ideas worth considering:

1. Provide a docisfy plugin "starter" or a sample repo to use as a starting point.

   This would make life much easier for the community and help enforce acceptance criters (below).

2. Define acceptance criteria for all docsify plugins.

   This is critical for docsify because unlike static sites, a docsify-powered site requires Javascript to render content. If a docsify plugin throws an error, it is almost certain that site functionality will be broken.

   Here are a few idea for acceptance criteria:

   • Specify the version of ECMAScript plugin developers should target. For docsify v4.x, ES5 is the required target to ensure IE11 support. This means dev must either author their plugin with ES5 syntax or transpile their code from ES6+ to ES5. For docsify v5, we'll have to look at our supported browser list to determine the appropriate ECMAScript version to target.
   • Plugin code must be wrapped in a try { ... } catch(err) { ...} statement to prevent a plugin error from breaking a site.
   • Plugins must make their version number accessible to other plugins for interoperability. Docsify addons like docsify-themeable and docsify-tabs already do this by adding an object to the global $doscify object ($docsify.tabs and $docsify.themeable) with a version key and value. The goal is to allow both docsify and other plugins to determine which plugins are active and, if necessary, modify their behavior as needed.
   • Plugins must specify a compatible docsify version to prevent breaking sites when a new version of docsify is released. For example, consider a v4 site that is configured to load the latest version of docsify and multiple plugins. If docsify v5 is released using the same URLs, the v4 site will automatically be "upgraded" to v5 but will likely break as a result of trying to load v4 plugins. This safeguard would allow docsify (or the plugin itself) to determine if it is safe to run the plugin before doing so, which would at least allow the site to load and function properly (albeit without incompatible plugin functionality). This wouldn't be necessary if users locked their docsify, theme, and plugin CDN URLs to a major version (see #780), but since they don't a safeguard like this is necessary.

Just some ideas to get started.

[jthegedus]

@jhildenbiddle re 1: I have a plugin template repo I have yet to publicize. I will see about moving it to this org and then we can iterate on it.

[anikethsaha]

@jhildenbiddle this is really an awesome suggestion. It would make the plugin integration much more strong and simple.

May be we should extract this suggestion into a new issue.

My 2 cents ⬇️

Also, I am thinking of creating a wrapper function something like this createDocsifyPlugin function that needs to be returned from the plugin. It will accepts the following data

interface PluginMetaI {
  version: String;
  docsifyVersion: String;
  polyfillURL?: String;
  definition(hook: Object): void;
  pluginDocsURL?: string;

  // SOme more meta datas,/
}

const createDocsifyPlugin = (PluginData: PluginMetaI): Promise<void> => {
  const { version, docsifyVersion, polyfillUrl, definition } = PluginData;

  // some validation of the datas
  // like loading the polyfill

  // ...

  return new Promise((res, rej) => {
    try {
      res(definition(hook));
    } catch (err) {
      rej(err);
    }
  });
};

export default createDocsifyPlugin({
  version: "4",
  docsifyVersion: "4.11.0", //minimum this version is required.
  definition: hook => {
    hook.beforeEach(function() {});
    // ...
  }
});

createDocsifyPlugin will be a global function I guess so that inline plugins can be returned as well. I used promise so that we can handle the async and errors better.

This is just an example I am thinking of the implementation. We can discuss this for a better approach.

[jhildenbiddle]

Plugin / wrapper discussion moved to #1209.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[EternalDeiwos]

@anikethsaha You mentioned possibly using markdown-it as the markdown parser in #823 -- is this still being considered because that would be fantastic. It would be really great to have a pluggable parser.

[trusktr]

Rather than try to pile a lot of things for a huge release, which we don't have time for, let's release features when as we go, more organically.

None of the major bullet points listed in the original post are breaking changes, but feature additions, which don't require a breaking change.

If we have an idea for any change that improves Docsify, we can make an issue or discussion for it, then a pull request if we think the change is worth it, including the appropriate version bump for it whether it is a patch, minor, or major.

By following this approach, we can keep making progress and not stalling a bag full of ideas for one huge major version bump. All of the original points can technically be added in v4.

As a general rule, let's try to keep backwards compatibility as much as we can.

So, I will close this, and let's open specific topics, and try to avoid breaks if possible unless something needs to change to improve end users experience.

[trusktr]

I forgot to mention, after getting things moving and making meaningful changes and bumping as necessary, including major bumps, we will be in better shape to stabilize and have less major bumps.

We should publish a nice migration log that makes it easy for people to update. Three.js follows the above approach, and this is what their migration log looks like:

https://github.com/mrdoob/three.js/wiki/Migration-Guide

Let's take inspiration from this, and move forward.

Three.js doesn't even have patch or minor bumps, only major.