docs integration

[shaunlebron]

Context: The pipeline for the cljs api docs handles a lot of complexity behind parsing/supplementing API data, and produces a plain data file (see its format here). This should be the only interface between the site and the docs.

Updating the docs should look like:

./update-docs.sh
./publish.sh

The update script should download and read the latest API docs file: https://github.com/cljsinfo/cljs-api-docs/blob/catalog/cljs-api.edn

It should then generate files in site-jeykll/ after reading the latest docs:

auto-generated

The following files should be generated. All should have a comment at the top describing that it was created by the update script.

• _data/docs/history.json (see data files in jekyll)
• docs/<fullname>.md files for symbol pages, containing:
  • front matter such as symbol or namespace names
  • content blocks for markdown content (description and examples)
• symbol references file for simple cross-referencing of symbols
• doc-search-index.json available to JS for dynamic search sidebar

  not generated

• docs/history.md - this will render a history table and API changes by using the generated data in site.data.docs.history
• _layouts/docs/symbol.md - symbol pages (set window.__cljs_api_doc__.symbol so sidebar knows what symbol we're in)
• _layouts/docs/syntax.md - syntax pages are rendered slightly differently
• docs/index.md - starting point, using the symbol layout.

  sidebar

We need a sidebar for searching/exploring docs that will require some dynamic behavior. This'll be a clojurescript React component.

On init:

1. Check window.__cljs_api_doc__.symbol to set current symbol
2. Check ?search= to set current query string for search term.
3. Scroll the sidebar to accomodate current category, symbol, or search result.

Explore mode:

1. display category column (highlight current), update current category on click.
2. display symbols column (highlight current), navigate to symbol on click.

Search mode:

1. if search field has anything, display results instead of category/symbol columns
2. display results with highlighted matches
3. each result link navigates to its symbol URL appended with ?search=
   • this allows the user to still see search results across pages
4. Display a full search > link to navigate to a future page showing more details of each result

[shaunlebron]

gone a different direction. ditched jekyll, and will have to forgo search until later