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

Create demo Jekyll based on markdown files found in the CoMPAS repositories #186

Open
Sander3003 opened this issue Oct 23, 2023 · 4 comments
Assignees

Comments

@Sander3003
Copy link
Member

Sander3003 commented Oct 23, 2023

Hypothesis; we believe that Jeckyll can publish all documentation at once on Github

Test; to verify that, we will make an Example Jeckyll

Metric; and measure if we can see all existing documentation in the current repositories

Criteria; we are right if:
No documentation changes are needed
Files are close to the code
Easy to read
Easy to navigate

Theme to use:
https://jekyllthemes.io/theme/bulma

Acceptance criteria:
Existing documentation
Generate pages dynamically based on the MD files found in the repositories
Convert https://com-pas.github.io/compas-architecture/ into the Bulma theme

Spike: 8 hours (excluding sharing) + 4 hours sharing
Outcome: example setup with the plug-ins / session to discuss the results

@pascalwilbrink
Copy link
Member

pascalwilbrink commented Oct 25, 2023

After playing around with MKDocs, I believe that we can better make use of Jekyll (or Hugo, suggested by Tamas).
Both do the same.

Hugo is faster to generate HTML pages, but this is not really worth it, since we only have a few pages.
Jekyll offers plugins where we can extend the usage

@Sander3003
Copy link
Member Author

Jekyll:
Pros: Widely used and allows plug-ins
Cons: Slower build time

Hugo:
Pro's: Fastest
Con's: No plug-in

MKdocs:
Pro's:
Con's: No template generator

@Sander3003 Sander3003 changed the title Create demo with MK docs Create demo Jeckyll based on markdown files found in the CoMPAS repositories Oct 30, 2023
@pascalwilbrink pascalwilbrink changed the title Create demo Jeckyll based on markdown files found in the CoMPAS repositories Create demo Jekyll based on markdown files found in the CoMPAS repositories Dec 13, 2023
@Sander3003
Copy link
Member Author

Todo: Upload the script to get the markdown files.

@Sander3003
Copy link
Member Author

Tested here: https://openscd.github.io/Documentation/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Development

No branches or pull requests

2 participants