myst-lang / myst-docs Goto Github PK
View Code? Open in Web Editor NEWDocumentation viewer for Myst projects.
Documentation viewer for Myst projects.
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:
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.
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:
Line 132 in fcc0ed7
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).
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.
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
.
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.