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 faq directory structure #109

Closed
wants to merge 1 commit into from
Closed

Conversation

StefanJum
Copy link
Member

This pr adds a directory structure for common issues and faqs, similar to what we have for the hackathon sessions.
All the content is placed inside docs/common-issues/content and refered in docs/faq.md via the readfile shortcode.

Likely we will have another front page where common issues will be added since they refer directly to issues, not questions, but I would suggest we keep the content in the same docs/common-issues/content directory and we name the issues something like Common-Issues_Issue-Name.md, while the name of the frequently asked questions will look like the ones in this commit: Frequently-Asked-Questions_Question-Name.md.
Any other ideas on this are welcome.

Content is taken from #31.

Signed-off-by: cristian-vijelie cristianvijelie@gmail.com
Signed-off-by: Stefan Jumarea stefanjumarea02@gmail.com

Signed-off-by: cristian-vijelie <cristianvijelie@gmail.com>
Signed-off-by: Stefan Jumarea <stefanjumarea02@gmail.com>
@nderjung
Copy link
Member

nderjung commented Sep 4, 2022

Hi @StefanJum,

we defintely need a FAQ section for the docs site! I'd like to structure it, however, with a little more integration into the Hugo partials system. I think creating a new file for each FAQ item is fine, considering that there may be many items and any item can be paricularly verbose.

As a result, an FAQ page should be added as custom page type with custom archetype. The page can iterate across each file item to generate a prompt as well as a permalink which takes you to the full explanation page.

Additional notes:

  • I'd rename common-issues folder to faq.
  • Each file should be the "slug" of the URL name, e.g.: unikernel-vs-container, and so: content/en/faq/unikernel-vs-container.md.
  • Each file should contain the newly defined archetype which must include both the question and the answer:
    ---
    question: "What's the difference between a unikernel and a container?"
    ---
    Unikernels are VMs.  For more information, please read the [...]
  • The main FAQ page should then be integrated into the layouts/ dir where each file's archetype is parsed iteratively and the question is laid out as a URL. This means adding a new FAQ only requires adding a new file, and not updating a list anywhere else.

@StefanJum
Copy link
Member Author

Thanks a lot, @nderjung.
I am not very experienced with hugo so it may take some time, but I will look into that and let you know how it goes.

@StefanJum
Copy link
Member Author

Superseded by #391

@StefanJum StefanJum closed this Jul 20, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants