Comments (5)
Related to #44
from swift-doc.
I'm using lunr.js on https://kean.blog/nuke/guides/welcome and can build something similar for swift-doc. I built it using plain JS without any dependencies.
from swift-doc.
@mattt, do you have any preferences in terms of the implementation or design? I'm not entirely sure where to add it. I have a couple of options in mind (these are just mockups).
Features
- Search on the site
- And search on the page (?)
- Keyboard navigation
- Start searching by pressing
f
- Generated index should be served as a plain json file so that it could be used on other websites (use-case: cross-site search from https://kean.blog/nuke/guides/welcome)
Input Position
Option 1
Add it to a header and (optionally) make the header fixed.
Option 2
Add it to the contents. I think this one looks nice, but there are a couple of potential issues.
Cons:
- It can give the wrong impression that it search on the current page instead of the site. To mitigate it, we can do both and provide two sections with search results: "On this page" and "On the site."
- Keyboard navigation. If the user presses
f
for search, we will have to scroll (?) to the top of the page. Not the end of the world.
Option 3
It could also go somewhere above the ToC.
Pros: looks nice and is always visible without messing with the header size.
Search Results
I think it would be nice if the search results would simply appear on the page using the same design as currently used for the main content. (Highlighting a selected item for programmatic navigation).
from swift-doc.
To collect additional data and to get an idea what is expected and familiar for users, I did a short benchmark (see details below). Search bar in the header seems to be the most used pattern by now used in developer documentations.
And I completely agree with your reasoning, @kean. I think you described the pros and cons of the different approaches really well. Option 2 definitely looks like it searches on the current page only. Personally, I like the visuals of Option 3 with the search in the side bar the most. But there I also see the problem that users could think that it only searches for the current page, especially because it's very close to the "on this page" element.
Benchmark details
Stripe has the search bar in the header.
Apple has a super small search icon in the header which expands to a search bar
Github has the search bar in the header
React has the search bar in the header
Twilio has a search bar with rather bad contrast in the header
from swift-doc.
Thanks, @Lukas-Stuehrk. I also think the header is the most reasonable choice. Just to add to your list:
- Microsoft – search in the header and they don't even worry about fixing it, which I think makes sense for an API Reference where pages are not too long
- Google – also header, this time fixed. swift-doc doesn't really have a header currently.
As for the search results, maybe it's best not to re-invent the wheel and add a dropdown with search results. I can come up with something basic and it can be improved later if needed.
from swift-doc.
Related Issues (20)
- Operators are not included in the generated documentation if there are multiple operators with the same name
- Add designs to accommodate all types of callout in discussion in HTML output HOT 1
- Add section to README for troubleshooting installation HOT 1
- Character substitution in file names can lead to collisions HOT 1
- Localize generated output HOT 1
- Migrate from Docker Hub to GitHub Container Registry HOT 1
- Improve estimation of diagram boxes
- Feature Request: support x-source-tag
- Loud GitHub diffs
- Feature Idea: HTML folders based on project folders HOT 1
- Comment tags are not recognized HOT 3
- Generate Diagram in Swift-doc
- Documentation links to non-existent internal protocols HOT 2
- Group management
- `Error: The loaded '_InternalSwiftSyntaxParser' library is from a toolchain that is not compatible with this version of SwiftSyntax` HOT 2
- Support for local html file browsing
- Feature request: Declarations with a documentation comment containing `:nodoc:` are excluded from the documentation.
- Error to load CSS in Index.html [Fix] [CSS] HOT 2
- Displaying documentation coverage with GitHub Action?
- Documentation coverage report
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from swift-doc.