Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add details toggles for FAQs #79

Merged
15 commits merged into from
Aug 9, 2019
Merged

Add details toggles for FAQs #79

15 commits merged into from
Aug 9, 2019

Conversation

dennisreimann
Copy link
Contributor

As requested in #72 this introduces the custom block ::: details which can be used to initially hide long-form content and first present a summary. In this case the FAQ leverage it to better structure the questions and answers and provide a better overview than the previously used table of contents.

Thoughts: Even though I really like the output, my concern about this is that we need to use a custom block for that and the authoring of the markdown does not seem intuitive. IMHO the headlines plus plaragraphs feel more natural. Feedback welcome!

If merged, this would close #72.

Signed-off-by: Dennis Reimann mail@dennisreimann.de

@dennisreimann dennisreimann requested a review from a user August 5, 2019 19:32
@dennisreimann dennisreimann added FAQ About the FAQ ready for review Waiting for review and discussion structure Regarding the structure of VuePress and GitHub visual Regarding the UI of the documentation labels Aug 5, 2019
Copy link

@ghost ghost left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really like this layout and reading flow!
All the questions are nicely seen right from the start of the page, and the click comes natural and easy.

I give my ConceptACK, although I see your point with the custom markdown extension... Are you comfortable to merge this, or do you need some proper review on how you implemented it @dennisreimann?

I will push to this branch the changes needed so that all the FAQ are in this structure. Then we can decide weather or not to merge it later after review.

@ghost
Copy link

ghost commented Aug 6, 2019

Ok, I think that I now have all the FAQ properly integrated. A couple things that I noticed:

  • The question is no longer shown in the sidebar as ### header. I think it would be good to have it in here, and when clicked, to jump to the question and open it. This means that we can not link to a specific question - this is a deal breaker.
  • when there is a text box :::danger::: in the question, then this messes with the drop down, it closes right after this text box.

@dennisreimann
Copy link
Contributor Author

All of that makes me wonder if this is a good approach. From the semantics of the output this would be the right solution, but it has too many tradeoffs and makes things fragile on the authoring side, which I don't like.

I also thought about not hiding the HTML and exposing it on the authoring side (i.e. using <details><summary> directly in the markdown), but that feels very unnatural and is brittle too (for instance teh markdown inside those blocks does not get rendered anymore).

All in all I think we should settle this.

@dennisreimann
Copy link
Contributor Author

when there is a text box :::danger::: in the question, then this messes with the drop down, it closes right after this text box.

Regarding nesting of custom blocks: outer block start/end require more :.

@dennisreimann
Copy link
Contributor Author

Ok, I got it worked out. Please take another look @MaxHillebrand and let me know what you think :)

@dennisreimann
Copy link
Contributor Author

Ok, last revision, better than before, but stil not perfect: The sidebar hightlight gets tripped up and does not work well with toggling containers.
Improved the authoring side with normal headline handling, though.

I am leaving it to you Max, whether or not this should get merged. I am still not really happy with this, but would not invest any more time here, as this feels very fragile and would require upstream changes in VuePress to handle this properly.

dennisreimann and others added 12 commits August 9, 2019 12:10
As requested in #72 this introduces the custom block `::: details` which can be used to initially hide long-form content and first present a summary. In this case the FAQ leverage it to better structure the questions and answers and provide a better overview than the previously used table of contents.

Thoughts: Even though I really like the output, my concern about this is that we need to use a custom block for that and the authoring of the markdown does not seem intuitive. IMHO the headlines plus plaragraphs feel more natural. Feedback welcome!

If merged, this would close #72.

Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
@ghost
Copy link

ghost commented Aug 9, 2019

Ok, tested, it works decent:

  • drop down works
  • headers are shown in sidebar
  • hyper link to question works

One thing that might be further improved

  • when linking to specific question, drop down the content automatically

I really really really like the concept - I think it's much better than incumbent FAQ.

But I am concerned that you don't think it's a robust architecture... I guess that what we have now in this PR is "good enough", and if it requires a little more work to get it even better, then I think this might be worthy the investment of time.

Also, we might consider to communicate with the VuePress team to get them tinkering on this as well - maybe even offer them a bounty as thanks for their awesome work so far. [We have the budget of 1k USD per month, their tool has helped us a lot, so I'd like to consider them anyhow]

So I give concept ACK, but kick the issue back to you @dennisreimann in regards to implementation ACK, if you are comfortable enough with this PR, let's merge it!

@ghost ghost mentioned this pull request Aug 9, 2019
@dennisreimann dennisreimann reopened this Aug 9, 2019
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
@dennisreimann
Copy link
Contributor Author

Ok, I got it working, so please check again, @MaxHillebrand.

In case you think the current state is mergeable we still need to rebase it with your latest changes though.

Signed-off-by: Dennis Reimann <mail@dennisreimann.de>

# Conflicts:
#	docs/FAQ/FAQ-UseWasabi.md
@dennisreimann
Copy link
Contributor Author

Updated the branch to match the latest master. Please review and decide whether or not to merge before updating more FAQs :)

@ghost ghost merged commit 16acd08 into master Aug 9, 2019
@ghost ghost deleted the details branch August 9, 2019 17:22
This pull request was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
FAQ About the FAQ ready for review Waiting for review and discussion structure Regarding the structure of VuePress and GitHub visual Regarding the UI of the documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[FEATURE] drop-down for FAQ
1 participant