myst-lang / myst-docs

Documentation viewer for Myst projects.

Myst Docs

The official documentation viewer for Myst projects.

The site is automatically generated on-the-fly from the JSON structure emitted using the docs tool of the Myst interpreter.

Roadmap

• Improve general navigation.
• Enable direct linking to constants and methods.
• Add fuzzy searching for any object.
• Support additional pages for summaries/guides/etc.
• Allow drag-drop uploads for viewing documentation for a new project.
• Allow any project to upload documentation and get a static url.

myst-docs's Issues

Basic authorization and account setup

Users should be able to create accounts on the site for hosting their projects. Users with accounts would then get a pathspace for their account that all of their projects would go under.

For example, I have the Hygrometer project, and if I had an account on the site, it could live at drops.pm/faultyserver/hygrometer.

Move to a self-hosted application

While it's great that drops can be hosted directly through github right now, that won't work for the more dynamic features that we want to add in.

A simple app running on Heroku with a lightweight database should work pretty well for what we need, and will be free for a while. Data could be stored for free on S3 as well to keep the server even lighter.

Add a search bar

Being able to search for objects within the documentation is important for usability and helping people unfamiliar with the codebase (the main demographic of people using the site in the first place) to find what they're looking for.

I think the search results should also try to include some summary information about them to help users get to the right thing right away. I think that would include:

• The Full path to the object (e.g., what shows up in the url for referencing that object)
• The first sentence of the object description.
• For methods, at least one of the clauses should be included. Ideally all of them would at least be mentioned.

Obviously, the search should be a fuzzysearch as well. Typos happen and its frustrating when they aren't handled well.

The search should also be directly usable from a URL, and executing a search should add an entry to the browser history so that users can backtrack to it directly. One complaint that I (and many others from my experience) have with https://hexdocs.pm is that clicking off a search means the search gets lost and you can't go back to it.

I think using "fake" query parameters could work well for this. I'd like to see something like https://drops.pm/?equals work and perform a search for "equals". Since the query parameters are really just a string, this should work just fine for complex queries as well.

Droppable documentation loading

Since the documentation viewer is completely based on parsing a single docs.json file on the client side, it makes sense that users should be able to drag-drop their own JSON onto the site and have it loaded into the viewer automatically.

The site is already set up with dependency injection to make loading new documents easy, it's just a matter of adding a droppable area that reinitializes the site with the new data source.

Handling page refreshes would be a little more difficult, though I think it's fine to not support that at the start.

Linking to a `%` method fails

Example: https://drops.pm/#Integer#%

Going directly to that link will fail to load any documentation. Clicking #% in the sidebar of Integer will not take you to the method documentation.

This happens because % is a special character in URLs, and the browser is likely trying to interpret it as an escape sequence, but fails since there is no data after the character.

The culprit seems to be this line:

myst-docs/docs.js

Line 132 in fcc0ed7

let full_name = decodeURIComponent(window.location.hash.replace(/^\#/, ''));

decodeURIComponent is attempting to parse the escape character and failing, causing a JS error and stopping the rest of the execution.

I think decodeURIComponent could probably be taken out, or at least be made optional (i.e., try decoding, but fallback to the raw string if it fails).