Evaluate alternative static site generators

[muuki88]

With the upcoming prebid 8 release we again have the question on how to handle this in the documentation.
We have a prebid releases page in the references section, which gives a nice overview, but the documentation is lacking some info

• is this module/feature/config only supported in my prebid version as well?
• where can I find the specific documentation for my version

Currently, we solve this by adding meta data to bidders or specific configs/modules if there's a restriction on a prebid version.

Goals

There are a few goals we would like to achieve

1. Reduce friction between code and documentation
   1. no documentation PRs required for prebid.js changes
   2. generated API documentation, reducing the chance of out-dated-api docs
2. Allow a versioned documentation to time travel to the correct version
   1. Get rid of annotations in the documentation when to use what
   2. Always up-to-date download page
   3. separate versions for the different prebid projects along with a documented and implemented release process
      1. prebid.js
      2. prebid server (go & java)
      3. prebid mobile
3. Reduce code review remarks by
4. required types for certain layouts
5. enum / string literal union types for allowed values
6. Replace tables where possible with a more responsive / mobile friendly layout

Requirements

1. Easy to contribute like now - open a PR and change a markdown file
2. Migration with as a little as possible directory structure changes. See Rework navigation and update or remove outdated pages #5630 for a list of important pages

/download.html
/dev-docs/bidders.html
/dev-docs/publisher-api-reference/setConfig.html
/
/prebid/prebidjs.html
/dev-docs/getting-started.html
/dev-docs/pbs-bidders.html
/dev-docs/modules/userId.html
/dev-docs/examples/basic-example.html
/prebid-server/overview/prebid-server-overview.html
/dev-docs/bidder-adaptor.html
/adops/step-by-step.html
/dev-docs/publisher-api-reference.html
/troubleshooting/troubleshooting-guide.html
/dev-docs/adunit-reference.html
/overview/intro.html

4. Algolia support for site search
5. SEO support
6. Migrate all existing customizations
7. Google Analytics page view tracking

How to communicate bidder changes in a subversion

bidder changes something

Customizations

There are a couple of customizations and extensions in the code base.

Generating tables and list from front matter meta data

We use jekyll meta data to generate listings of things.

Using the layout meta data to provide a list of certain module types, e.g. layout: bidder or layout: userid

prebid.github.io/dev-docs/bidders.md

Line 23 in 5d9377d

{% assign bidder_pages = site.pages | where: "layout", "bidder" | where: "pbjs", true | sort_natural: "title" %}

Search Input Fields

prebid.github.io/dev-docs/bidders.md

Lines 30 to 36 in 5d9377d

	<input type="text" id="autocomplete-filter" class="autocomplete-filter">
	<script src="https://cdnjs.cloudflare.com/ajax/libs/awesomplete/1.1.5/awesomplete.min.js" integrity="sha512-HcBl0GSJvt4Qecm4srHapirUx0HJDi2zYXm6KUKNNUGdTIN9cBwakVZHWmRVj4MKgy1AChqhWGYcMDbRKgO0zg==" crossorigin="anonymous"></script>
	<script>
	var AutocompleteList = [{% for page in bidder_pages %}{ label: '{{ page.title }}', value: '{{ page.url }}' },{% endfor %}];
	</script>
	<script src="{{site.baseurl}}/assets/js/autocomplete.js"></script>
	<div class="c-bidder-list-group" markdown="1">

Download Page

This page enables users to download a prebid.js distribution with the selected modules

https://github.com/prebid/prebid.github.io/blob/master/assets/js/download.js

Docusaurus

Docusaurus overs most of the needed features. However the devil is in the detail.

Multiple versioned folders

Versioning is possible: https://docusaurus.io/docs/versioning
Also with multiple content roots: https://docusaurus.io/docs/docs-multi-instance

However displaying those different versions is not natively supported yet:
facebook/docusaurus#5415

Build dynamic page content

Docusaurus currently has no way to build dynamic page content based on all existing pages. See the full discussion here, which contains some options on how to solve this (for us at least)

facebook/docusaurus#4045 (reply in thread)