search

pester / docs

Source files for the Pester website.
https://pester.dev
MIT License
41 stars 77 forks source link

Search index missing New-PesterConfiguration codeblock #280

Closed fflaten closed 2 weeks ago

fflaten commented 1 year ago

Checklist

Link to page

https://pester.dev/docs/commands/New-PesterConfiguration

What is the issue?

Searching for SkipRemainingOnFailure returns no result even though it's documented in the New-PesterConfiguration help. I assume it's because codeblocks are excluded from indexing.

Suggested fix?

Is it possible to include codeblock for that specific page? Or should we focus on documenting all the options as part of other pages. Ex in this case as a section @ https://pester.dev/docs/usage/skip ?

bravo-kernel commented 1 year ago

It looks like this Algolia thread contains a similar question. https://discourse.algolia.com/t/experience-and-advice-for-dealing-with-indexing-of-code-in-software-documentation/8307/3

It also mentions a specific tag that will help the DocSearch crawler to know what are the part important but I cannot seem to find an example. To me, that sentence reads as if it would be possible to include the codeblock only for that specific page.

fflaten commented 5 months ago

I'm considering generating this directly to markdown as a section in docs/Configuration maybe. Just like we do now in New-PesterConfiguration comment help.

Will fix this, have improved formatting and ToC for easier navigation.

Maybe also extract the generated help from New-PesterConfiguration to about_PesterConfiguration.txt in the module.

fflaten commented 5 months ago

Made a PoC. Thoughts?

List: image

Table with FQON (fully qualified option name 🤓): image

Table with option name: image

bravo-kernel commented 5 months ago

Awesome, the FQON table is the most readable one for me. Super clear.

fflaten commented 5 months ago

Thanks. I'm undecided between FQON table and list. Table is bad on phone in portrait mode, while list use a lot of vertical space.

bravo-kernel commented 5 months ago

How does the Tanstack table look bad on mobile? I use it myself and once I accepted the horizontal scrolbar it looks fine for me.

fflaten commented 5 months ago

How does the Tanstack table look bad on mobile? I use it myself and once I accepted the horizontal scrolbar it looks fine for me.

When I wrote it they overflowed and broke the layout. Fixed in https://github.com/pester/docs/commit/68bffbe0e80d75664b62bf3c60ff6416d8dbf358 with same wrapper used on tanstack tables earlier. 👷‍♂️ 👍

Personally not a fan of horizontal scrolling though.

bravo-kernel commented 5 months ago

Yes, the overflow is a thing :)