13 seconds build time per page


I am complete beginner to Jekyll and I have been tasked to create documentation for our big C# Framework. We decided to go for Just The Docs (GitHub - just-the-docs/just-the-docs: A modern, high customizable, responsive Jekyll theme for documentation with built-in search.) theme as built-in search was a must and it looked very minimalistic and nice.

I went to writing articles and everything was working fine - until I wrote a script that generates markdown files from our library. I now have over 2000 markdown files of a long documentation with a lot of nesting and references to each other. (Think Enterprise size library). I checked how long does it take for one page to load and it’s about 13.5 seconds. If you do the math it will take me few hours to build the whole documentation.

Our old solution using DocFX built time as a whole was around 7 minutes. There has to be a way to make it at least come a bit close to that I suppose.

So I have few questions:

  1. Is there a way to decrease this build time?
  2. Is there a way to cache built site so the next built just builds the changed files?
  3. What information should I provide you with regarding my project?

I checked how long does it take for one page to load and it’s about 13.5 seconds.
To ensure I fully understand the issue, you are not saying it takes 13.5 seconds per page to load but 13.5 seconds to build, correct?

I’ll assume that is what you mean for the time being.

There are many reasons it takes a long time for your site to build, but as you say, this does seem quite lengthy. There are thousands of themes for Jekyll. I do not know Just The Docs, but I have heard of others using it.

:link: Share your repo, if possible

The best and easiest way for any of us to help you here is to share the repo if it is public so we can take a look at it, maybe clone it and see what build issues there may be.

:stop_sign: Temporarily disable search functionality

The first thing I might do is look at your _config.yml file. I looked at the Just The Docs file, which contains many configurations. While I am not saying “do not use this feature,” you might be able to debug at least what is causing the slowness. To start, I would change search_enabled: true to search_enabled: false and rebuild the site to see if there is a noticeable impact.

:person_raising_hand: Questions

  • What version of Jekyll are you using?
  • What version of Ruby are you using?
  • Are you using any plugins?
  • Are you using incremental builds?

you could try doing jekyll b --profile and it should show you some info on what is taking so long.

There is also an incremental command to build just the pages that changed but it is still experimental and may not work properly in all cases.

13-seconds per page is definitely appalling. Are you by any chance using Jekyll 3.9 or older? If yes, could you try with Jekyll 4?
However, if you’re using Jekyll 4.3.1, try updating to v4.3.2. If it’s still this slow with v4.3.2, I’d definitely like to clone your repository and see what’s the reason.


Thank you all for answers.

I am actually being serious when I say ~13s per page (post? / markdown file). So the build would be in hours.

Jekyll version: 4.2.2
Ruby version: 3.1.2p20
Plugins: jekyll-feed
Incremental builds: I have not been using incremental build - will start to do that from now.

I have tried turning off the searching options but there was no difference that I could notice.

I am building my project with: bundle exec jekyll serve --verbose --livereload --incremental
Reading of files happens fast but rendering is what is slowing the process down.
When running the above mentioned command below lines last around ~13s, then it moved to next file.

Rendering: docs/(FRAMEWORK)-api/Generated/(REDACTED).(REDACTED_OTHER_FRAMEWORK).BLEServices/ASHAService/ASHAAudioStatus.md
Pre-Render Hooks: docs/(FRAMEWORK)-api/Generated/(REDACTED).(REDACTED_OTHER_FRAMEWORK).BLEServices/ASHAService/ASHAAudioStatus.md
Rendering Markup: docs/(FRAMEWORK)-api/Generated/(REDACTED).(REDACTED_OTHER_FRAMEWORK).BLEServices/ASHAService/ASHAAudioStatus.md
Post-Convert Hooks: docs/(FRAMEWORK)-api/Generated/(REDACTED).(REDACTED_OTHER_FRAMEWORK).BLEServices/ASHAService/ASHAAudioStatus.md
Rendering Layout: docs/(FRAMEWORK)-api/Generated/(REDACTED).(REDACTED_OTHER_FRAMEWORK).BLEServices/ASHAService/ASHAAudioStatus.md

I am providing you a repository.
Natromitus/jekyll-doc-tsl2 (github.com)

I had to do few things so I won’t get into trouble:

  1. I had to do some patchwork censoring so it isn’t plainly obvious what the frameworks are.
  2. I had to delete a lot of files from the repository - resulting now in much faster build.
    • articles disclosing internal documentation
    • around 2000 markdown files generated from Framework used for development
    • images

I noticed that after deleting a lot of pages a render time per markdown file went down by half. Less markdown files there are faster the time is per markdown file.

Here you can see the issue: it iterates over all your content in all your pages. It probably does that also for the search, but I did not look into that.

{% include nav.html pages=collection key=collection_key %}

The include nav.html is used in the sidebar.

The code is not written with performance in mind, as you can see above. Some very poor choices have been made in building this theme. Having frontmatter like this is terrible from a maintenance POV. The performance of this theme could be fixed by having an autocollapsing menu that gets its active state from javascript. In that case it can be generated once instead of 2000 times (the amount of pages you have).

layout: default
has_children: True
permalink: /(REDACTED_FRAMEWORK)-api/ReSoundSETTestwareTestCaseActionsRatatoskAssembly

Also, I would not use Jekyll, but Hugo for this purpose (generating a big documentation website). If you want me to port it for you, contact me on joost@vdschee.nl.

1 Like

Thank you for providing a link to a public repository, @Natro. However, I was unable to find a file with ASHAService in its relative_path. I’m guessing that it probably got thrown out during the censorship.

Since it has been pointed out that there are bits of non-performant bits in the theme, you’re either better off creating a custom theme from scratch or jump the ship and switch to another static-site-generator such as Hugo which is known for its fast build times.

1 Like

Yes most likely got disposed during censorship, sorry about it :frowning:

Ah, that’s a shame I really liked the theme and the documentation was almost done. I guess I am jumping ship.

Thank you very much guys.