# Pages that are not part of a package

Those pages include:
- package-relevant pages:
- Landing page for the package
- Landing page for the list of libraries
- Landing page for each library
- Hierarchy pages:
- The list of all packages
- The list of versions for a package
- Other (user written page)
- Pages that exist in the Jane hierarchy without being part of a package

    /lib/foo/doc/...                        # not those ones
    /doc/...                                # those ones
    /not_a_library/random_folder/xx.m[l]d   # those one too (do they exist?)

For those pages, we need more info from Jane Street

## Question about those pages:

- What do we expect them to contain? Are they generated by the driver, the user, odoc itself?

- Can they be linked to? With references (which one?), or with hardcoded html links?

For instance, one may want to link to a package landing page, from the list of package.

- Can they redirect?

For instance, one might want to redirect the package landing page to the documentation landing page, when available. Note that redirecting is possible even in the case of static files served over `file://`.

Not necessary!

- What breadcrumb do they contain?

Do "package-relevant" pages contain different kind of breadcrumbs, compared to "hierarchy" pages?

Do normal pages contain breadcrumbs over the limit of its`-P`/`-L`?

- What sidebar do they contain?

Same question as for readcrumbs: Should "package-relevant" vs "hierarchy" page be treated similarly? Differently from normal pages?

- Do we expect some of these pages to be written by the user and not by the driver?

If so, we should specify how to link to them/how to link from them (they might not have a "current root")

Where do we install those pages in the opam switch?

- How to avoid "multiple landing page" problem? The clicky clicky hierarchy?

- During linking, maybe we could check which parent pages are present to avoid generating links to 404? No.

## Conclusion

- We do not want yet to provide a way to user to write any new page (in the opam installed doc building convention)
- No way in user-written pages to link to driver-generated pages such as package landing page. For driver-generated pages, we can link to driver-generated pages using "fake" `-P` with driver-generated names.
- Landing page for packages is like in ocaml.org (README etc) in the "convention for buliding opam installed packages"
- Breadcrumbs:
- We use info from our own `-P`/`-L` to generate a not clickable breadcrumbs with "`Lib: <library name>`"
- For now: `Package: <package name> >> Lib: <library name> >>` ?
- Then experiment with our driver and the odoc CLI to shorten everything (urls, breadcrumbs) when the library name and package name are the same
- Do we want a `"Top" >> ` at the beginning for odoc driver/dune docs/odig/Jane Street usecases? Not for now?! If we do it, it should depends on options passed to the html driver.
- No breadcrumbs for the hierarchy pages (the one outside of a packagem such as the list of packages)
- For "package relevant pages" (list of libraries, package landing page, library landing page):
- Use `--current-package` to have `Package: <package name>` for package landing page and library lists.
- Use `--current-package` and maybe `-L` or `--current-lib` to have `Package: <package name> >> Library: <libname>` for library landing page.
- EXPERIMENT!
- Sidebar
- For package-relevant pages:
- Same global sidebar as package pages
- For other pages:
- No global sidebar?
- Jane usecase:
- We need to be careful to make the sidebar useful. Depends on how "packages" are created from JS repo: the global sidebar might be uselessest or uselesser if the packages are too big or too small.
- This package grouping should be based on the filesystem hierarchy.

## Discussion about landing pages

What should be the landing page of a package?

In ocaml.org, the landing page contains README, dependencies, ... and you can go to the documentation landing page from there
In odig, the landing page is the `index.mld` with some content added at the bottom.

Should we move `pkgname/doc` folder to `pkgname`?

We can make it a convention that landing page for packages is like in ocaml.org (README etc).