docs.prebid.org source

This repository contains the source files for the Prebid.js documentation site at Prebid.org.

Please see the sections below for more information:

• Contributing
• License
• Prerequisites
• Running Jekyll Locally
• Building Assets
• The Downloads Page
• Thanks

Contributing

Thanks in advance for your contribution!

For smaller changes, such as fixing a typo or adding a new section to an existing page, submit a pull request.

For larger changes such as reorganizing the site and moving/removing content, you may want to open an issue so we can discuss the work beforehand. This is a good idea because:

• We want to value your time, so you don't do unnecessary work
• We want to value our users' time; we don't want to break links and bookmarks for users

License

All docs are under the license shown in the LICENSE file in this directory.

Prerequisites

The site is hosted on GitHub pages, and uses Jekyll to generate the HTML. Jekyll is written in the Ruby language.

1. follow the instructions at jekyllrb.com/docs/installation/ for your OS
2. gem install github-pages
3. start Jekyll as described below

For CSS, the site uses Jekyll board tools to compile SCSS down to CSS.

1. Install boostrap via npm install to make the build work
2. Jekyll assets management
3. Jekyll SASS plugin

The markdown files are linted via markdownlint-cli. VSCode supports the .markdownlintignore file. You may need to configure the disabled rules specified in .markdownlint.json directly in your project settings. You can invoke linting in CLI via

markdownlint --config .markdownlint.json "**/*.md"

Running Jekyll Locally

Before submitting a pull request, you should run the site locally to make sure your edits actually work.

To get started editing the site and seeing your changes, clone this repo and enter the following commands in your terminal:

JEKYLL_ENV=production bundle exec jekyll serve --watch --incremental

Site search uses Pagefind, which indexes the built site. To try search locally, build the index once (with Node.js installed) while jekyll serve is running; Jekyll keeps the _site/pagefind folder between rebuilds:

npx -y pagefind --site _site

You should see output that looks something like this:

Configuration file: /Users/me/git/prebid.github.io/_config.yml  
            Source: /Users/me/git/prebid.github.io  
       Destination: /Users/me/git/prebid.github.io/_site  
 Incremental build: disabled. Enable with --incremental  
      Generating...   
                    done in 13.596 seconds.  
 Auto-regeneration: enabled for '/Users/me/git/prebid.github.io'  
Configuration file: /Users/me/git/prebid.github.io/_config.yml  
    Server address: http://127.0.0.1:8080/  
  Server running... press ctrl-c to stop.  
...  
...  

Open the Server address URL in your browser, and you should see a locally running copy of the site.

Checking Links

CI checks internal links and anchors in the built site with lychee, configured in lychee.toml. To run the same check locally, install lychee and run:

npm run linkcheck

Building Assets

• npm run dev to build unminified CSS for development
• npm run prod to build minified CSS for production
• npm run watch to use Browsersync to rebuild CSS on demand and reload the browser

The Downloads Page

Please don't submit PRs to the Prebid.org downloads page. That page gets updated in tandem with the Prebid.js release process.

The Downloads page is generated from the Markdown bidder adapter docs, so the process for updating is:

1. Your adapter code is merged into Prebid.js
2. Your bidder docs PR is submitted over here to the docs site
3. Your adapter code is included with a release
4. Once your adapter code is actually released, we merge the adapter docs PR, and the Downloads page is automagically updated with a checkbox to include your adapter.

This means an adaptor is not available to download from Prebid.org as soon as the code gets merged into Prebid.js - it will be available after the next release (usually in a couple of weeks).

Liquid Templating

• jekyll - check for non empty

Markdown for AI Agents

Every page is also published as its raw Markdown source: replace .html in a page's URL with .md, for example https://docs.prebid.org/dev-docs/bidders/msft.md. _plugins/raw_markdown_generator.rb copies the sources at build time.

• /llms.txt indexes all of them by section, following llmstxt.org. It's generated from each page's title, description and biddercode front matter, so keep those accurate.
• Each page's <head> links its Markdown with <link rel="alternate" type="text/markdown">, and documentation pages (not the homepage) show a "View as Markdown" link above the content.
• Liquid tags such as {% include %} are not expanded in the .md files, so put content that agents need in the page itself rather than in an include.

Codex

To get started with Codex with Ruby 3.4.4 preinstalled on this repo, you can set up your environment like this

echo "3.4.4" > .ruby-version
export NOKOGIRI_USE_SYSTEM_LIBRARIES=1
gem install jekyll bundler
npm install boostrap
gem install github-pages --no-document --force
npm install -g markdownlint-cli
bundle install

Codex can then check for linting success with

markdownlint --config .markdownlint.json "**/*.md"

Thanks

Many thanks to the following people who have submitted content to Prebid.org. We really appreciate the help!