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 Feat/5.0 #802 (The original Implementation)
• We can either continue on Feat/5.0 #802 or create a fresh PR for this (@QingWei-Li thoughts ?)
• docsify-cli implementation ref Generate static HTML docsify-cli#55
• Original issue Generate static HTML site (static site generation, SSG) #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]

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.

[stale]

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:

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? 🤔

[scruel]

I don't think this would be necessary, for crawlers, we can just provide them the hidden URLs which will redirect to markdown file directly?

[weituotian]

好~(￣▽￣)~*

[jhildenbiddle]

Docsify may someday offer static site generation, but given the myriad of alternatives offering SSG it seems best for Docsify to continue focusing on its client-side site generation abilities.

Closing due to inactivity.