Generate static HTML site (static site generation, SSG)

[acathur]

Eagerly waiting for this function, maybe it can be added to docsify-cli.

EDIT by maintainers:

• This is from #802 (The original Implementation)
• We can either continue on #802 or create a fresh PR for this (@QingWei-Li thoughts ?)
• docsify-cli implementation ref https://github.com/docsifyjs/docsify-cli/pull/55
• Original issue https://github.com/docsifyjs/docsify/issues/136

[QingWei-Li]

Sorry I don't have time to do now 😣, if you are interested, you can contribute.

[jrappen]

For comparison, maybe this is a start?

• https://github.com/webpro/reveal-md/blob/master/lib/static.js

[egoist]

so why not use gitbook 😄

[jrappen]

I found madoko:

• via npm
• https://www.madoko.net
• https://github.com/koka-lang/madoko
  • https://github.com/koka-lang/madoko/blob/gh-pages/reference.pdf
• https://www.microsoft.com/en-us/research/video/madoko-a-scholarly-markdown

You can:

• output static HTML
• output PDF
• include files
• style code in code blocks

[egoist]

@jrappen that looks cool, but seems it does the same things that gitbook can do

[dietergoetelen]

@QingWei-Li I'm new to docsify, would love to see this feature. I'm interested in contributing, can you point me in the right direction?

[egoist]

@dietergoetelen Seems the SSR API can achieve this https://docsify.js.org/#/ssr?id=deploy-for-your-vps

[QingWei-Li]

Hi @dietergoetelen, Now part of the compiler can run in Node, you can refer to docsify-server-renderer. We can read the files and then compile them like docsify-server-renderer do the same. Would you like to try it?

[maoueh]

@QingWeil-Li Was this close because it's now possible? Won’t fix?

[QingWei-Li]

@maoueh

GitBook is recommended if you need to build static files.

[luishdez]

But GitBook is a paid product, It's only free for "non private" projects. Can we at least leave the PR Welcome?

[gottlike]

@QingWei-Li

A really simple solution would be to just add a print-css and reference the browser print function with a simple button (printing to PDF can then be chosen by the user). What do you think?

[KerimG]

+1 on the feature request.

[sheljohn]

@jrappen I stumbled upon Madoko a while back. The main issue with it is that it is written in Koka, which no one knows apart from its author Daan Leijen, who is also the author of that package. For a while it was hosted on CodePlex, and it was really difficult to find the sources, let alone understand them, or contribute. I suppose this is now on GitHub because MS acquired the company... The reference manual looks absolutely amazing, and it's difficult to think that only one person is behind this; but IMO that summarises the project well. It looks awesome, but it's a black-box, written in sanskrit, with a single contributor.

@egoist Have a look at the reference manual; it serves a different purpose than GitBook. Madoko was designed to write scientific publication-like content; it supports LaTeX maths, internal references, citations, and footnotes out of the box. GitBook is meant to be an advanced documentation-writing tool, oriented towards web-publishing. Let us not compare pears and apples.

[weituotian]

@QingWei-Li can it output pdf? need!

[ideacco]

+1 on the feature request.

[yhhwpp]

+1 on the feature request.

[justerhan]

https://github.com/egoist/presite might be useful here

[trusktr]

Anyone that wants this feature, why do you want it? Has the live client-side markdown rendering been too slow for you? Is it hindering your user experience?

I am just curious, because performance updates for the sake of performance updates may not be as productive use of time compared to other features that are being planned. Please let us know if you encountered any performance problems that make a difference to the user experience (so far I haven't seen one that is significant, but it could be possible if you have giant markdown pages then that's an issue, for example).

@anikethsaha Since you listed this in v5, I'll re-open and add it to the 5.0 project so we can track it.

[justerhan]

Mostly because static files are easy to deploy across a cdn Service like Netlify

On Sun, May 10, 2020, 15:50 Joe Pea notifications@github.com wrote:

Just curious, anyone that wants this feature, why do you want it? Has the live client-side markdown rendering been too slow for you? Is it hindering your user experience?

@anikethsaha https://github.com/anikethsaha Since you listed this in v5, I'll re-open and add it to the 5.0 project so we can track it.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/docsifyjs/docsify/issues/136#issuecomment-626401785, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAGTNWYJT5DYMQ5ELKDQPTLRQ4VSPANCNFSM4DEBBIDA .

[trusktr]

@bountyx Markdown files are also static files.

[trusktr]

Ah! SEO!

That's a good reason to serve HTML, to make things more indexable by search engines.

[anikethsaha]

@trusktr there is an issue with plugins. most of the things in docsify is a plugin. we cant make them work if we don't have the DOM. So either we need to do it with jsdom while but this won't give 100% accurate results.

This will be a blocking issue for v5.

[trusktr]

Maybe also doesn't have to be for 5.0, it can be for "when it's ready". :) It's a bit complex.

Maybe we can build it on NW.js instead of JSDom.

[anikethsaha]

@trusktr yeah, we can remove this from the roadmap, this will be blocking issue

[trusktr]

👍

[vagra]

+1 on the feature request.

I using docsify for a online converter:

1. it can convert opml outline file to md;
2. then preview the md file using docsify;
3. and using the docsify server renderer, convert the md file to html file;
4. then using WeasyPrint (python package) convert html to PDF.

now i am blocked in the step 3. because docsify server renderer have some probreams:

1. it can't set basePath to local location;
2. I don't know how to save the rendered content to an html file at server.

[vagra]

need 2 function:

1. generate static html files for all docs;
2. genarate a html file for a specific doc;

[anikethsaha]

We have a blocking issue as plugins won't work if there is no DOM. Many plugins are using browser's features like local storage.

So i am not sure how long it will take or even it will be done or not

[trusktr]

Do plugins work with Docsify's SSR?

[anikethsaha]

yea but after the mounting of the DOM. plugins are intended to run after mounting when the core has access to DOM object ( location, window)

[trusktr]

SSR generates HTML, so we're pretty close to accomplishing the first version of this already.

We can just have it output HTML to the file system instead of to the client. We can use a simple crawler that crawls every link and for every link it can output each page to the filesystem using the Renderer from docsify-server-renderer.

Even without plugins, this can give us exactly the same result as we see at https://docsify.now.sh (but static instead of SSR).

With jsdom in place the DOM (although it is faked) will exist in order for plugins to use it. Plugins should work fine unless they do something extravagant like use WebGL or some brand new DOM APIs that aren't implemented yet.

We can write in the documentation how to test plugins for all three environments; SSR, Static, and real browser.

[trusktr]

Another idea: once we have the filesystem output, the same crawler can also index everything for the search results, and save it as static JSON that the client can fetch.

[anikethsaha]

I don't think plugins works in SSR.

Not sure though, I need to give it a test.

Happy to accept POC for this.

[anikethsaha]

I had the idea of rendering the main in jsdom and output the rendering in an HTML file.

[trusktr]

I had the idea of rendering the main in jsdom and output the rendering in an HTML file.

Yeah! I think we can get the vast majority of plugins working with JSDom in the mix. We run the renderer for each page, call the same plugin hooks, then take a snapshot. If a plugin needed to add a DOM event handler it won't matter for example. Some plugins might like to programmatically modify the DOM, which should be fine if it is done synchronously.

There might be plugins that work asynchronously though. We need to add a feature so that plugins can notify us when they are finished. Maybe we just allow all plugins to use async functions, and await for them to complete?

[trusktr]

@anikethsaha @jhildenbiddle I think we can achieve static site generation as a non-breaking change using the current docsify-server-renderer package. We just need to add some code to automatically run each page through the renderToString method. It can be a semver-minor update.

Then for a breaking change, once we re-vamp plugins to make them more robust and to allow them to work on both sides or similar, we can make the breaking changes.

Can we move to 4.x?

Note that if it is in the 4.x project board, it doesn't mean that we will strictly release it under v4, but that technically it can be released under v4 if we don't release a major version first. But if we, for example, prioritize to release some breaking changes in v5, then we can always move incomplete issues from 4.x to 5.x as changes that will be non-breaking in v5, while the new 6.x board will track new breaking changes. So we can keep issues rolling from board to board if they aren't completed yet.

[jhildenbiddle]

I'm guessing you probably already know what I'm going to say... :wink:

My vote would be to move to v5 for the following reasons:

1. SSR is a big feature for docsify. From a messaging perspective, we'll get more traction stating that SSR is now available in the NEW version of docsify than we will from tacking it on as a minor release to v4.
2. SSR will likely take a significant amount of time to implement and test. My preference is to trim the remaining work for v4 down to a minimum (i.e. critical bug fixes, security issues, dependency updates, etc.) so we can officially turn the corner to v5 as quickly as possible.
3. I think the logical interpretation of a card in the v4 Project is "this is work that will be released with a future v4 version of docsify". Adding issues to the v4 Project that we don't intend to ship with v4 is confusing, especially for new contributors. I'd prefer to keep things simple: "we need to clear out the v4 project first, so grab any issue you find there and when there are no more v4 cards we'll all move on to v5 cards". We can't say this if the v4 Project is a mishmash of stuff we will release in v4, stuff we could release in v4 if we wanted to (but we don't know if we will), and stuff that we won't release with v4 but it's in the v4 Project because people are actively working on it.

[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.

[qmjy]

I'm looking forward to it. 👍

[itymarcel]

Also looking forward to it. Is there any reason why this hasn't been merged yet? Thank you for working on this it's an amazing tool!

[MattRiddell]

Adding my voice to this - would make it a lot easier for me to get this deployed as a tool as I'd be able to send generated files to our documentation hubs.

EDIT: Sorry, also forgot to say what an awesome tool this is and how long I've been searching for something that fills my needs the way this does. I've used a tonne of documentation tools and this one aligns with my thought process and development methods by far the best. Doesn't hurt that the output is gorgeous too!

[juukee]

so when can we use it?

[weituotian]

好~(￣▽￣)~*

[hefengliang]

so when can we use it?

[BryanYin]

Is there any reason why this hasn't been merged yet? Thank you for working on this it's an amazing tool!

[trusktr]

It was experimental and didn't reach a state of being ready.

But! I'm interested in another plan:

I'd like to get Docsify to use Solid.js (I've been working with the Solid team) for its built-in and fast SSR and SSG capabilities. This involves first re-writing Docsify internals as Solid components. I started that work in the dom-with-solid branch here:

https://github.com/docsifyjs/docsify/compare/develop...dom-with-solid

As you can see there, some internal code is getting cleaner, for example this code,

function mainTpl(config) {
  let html = `<nav class="app-nav${
    config.repo ? '' : ' no-badge'
  }"><!--navbar--></nav>`;

  if (config.repo) {
    html += tpl.corner(config.repo);
  }

  if (config.coverpage) {
    html += tpl.cover();
  }

  html += tpl.main(config);

  return html;
}

was changed to

function mainTpl(config) {
  return (
    <>
      <nav
        class={`app-nav${config.repo ? '' : ' no-badge'}`}
        innerHTML={'<!--navbar-->'}
      ></nav>

      {config.repo && (
        <GithubCorner
          githubUrl={config.repo}
          cornerExternalLinkTarget={config.cornerExternalLinkTarge}
        />
      )}

      {config.coverpage && <Cover />}

      <Main {...config} />
    </>
  );
}

where GithubCorner, Cover, and Main are also components, all with a more modern reactive-declarative paradigm.

Besides SSR and SSG, this will allow us to more easily implement features like custom templates in a nice way. Imagine browsing a collection of templates to choose from (not just CSS themes), each with unique functionalities.

Up next I will remove the existing SSR implementation (in that branch, or a new branch based on that branch) because it has issues with plugins, and fixing that would be some work that would need to be totally replaced with the Solid SSR approach anyway (and I don't want to spend time working on two things when I can work on just one).

I'm also not sure that the team will approve of this direction. In that case I will be willing to make a fork to continue working on it there.

[sergeiromanov]

docsify looked so perfect for my case until I realized it doesn't generate static html :(

[weituotian]

好~(￣▽￣)~*

[mandrasch]

Just a quick thought: Could docsify be coupled with eleventy (https://www.11ty.dev/) or astro (https://astro.build/)? Guess for some use case (https://github.com/hibbitts-design/docsify-open-course-starter-kit for example) working without npm and without a build pipeline is a key feature of docsify. But for users wanting to have static output a (technical) bridge to eleventy or astro would be maybe an option as well? 🤔