Reviewed Changes

[DarikshaAnsari]

• Removed the in-toto website link from the navbar.
• Added the Learn More section back to the navbar.
• Added three more pages: News, Security Audit, and FAQ under Learn More section.
• Changed a "Software Supply Chain Protection" card button to link to system overview.
• Changed "Open, Extensible Standard" card icon to fa-book.

[netlify]

✅ Deploy Preview for in-toto-docs ready!

Name	Link
🔨 Latest commit	4f048dc
🔍 Latest deploy log	https://app.netlify.com/sites/in-toto-docs/deploys/66a87822b287ac0008ecec2a
😎 Deploy Preview	https://deploy-preview-7--in-toto-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[chalin]

@lukpueh and @DarikshaAnsari:

• There should not be a top-nav entry named "Learn more", instead I propose the following.
• Learn-more/faq should be under /docs/faq
• Learn-more/security-audit-23 should be a blog post under a Blog section. Blog should be what appears in the top nav
• Learn-more/news can appear as a News entry in the top-nav

Also see inline comments

[DarikshaAnsari]

@chalin, I have made all the changes you suggested. PTAL !!!

[chalin]

Good progress. See inline comments.

[lukpueh]

@lukpueh and @DarikshaAnsari:

• There should not be a top-nav entry named "Learn more", instead I propose the following.
• Learn-more/faq should be under /docs/faq
• Learn-more/security-audit-23 should be a blog post under a Blog section. Blog should be what appears in the top nav
• Learn-more/news can appear as a News entry in the top-nav

Just to clarify, in my review on slack I didn't mean to re-add the "Learn more" top-nav, but rather to migrate the contents from under the old "Learn more". The structure you suggest for this sounds reasonable. :)

Speaking of my review. @DarikshaAnsari Did you plan to address my other comments as part of this PR? It's okay if not. Just wanted to make sure they are not lost. I'll paste them again here:

• I like that the buttons and links on the landing page navigate to subpages inside docs. Maybe we can make this more consistent. That is, we map all buttons/links on the landing page to subpages . E.g. we could make "demo" and "friends" subpages in docs, to which "Try the demo" and "Explore integrations" point to. Those pages can then contain a short description of demo and friends repos and pointers to those repos. I think that might be a less disruptive experience, compared to when the user is directed to external pages right away on the landing page.

• Why are there two search bars, one in the right top corner and one in the left navigation column? (no need to fix this now, I'm just curious)

• Regarding content I am not sure if we should follow the recommendation from the cncf assessment and just re-publish the docs from python-in-toto as Getting started page. The documentation should represent the whole in-toto project, but the python-in-toto cli is only one of multiple in-toto implementations.

[lukpueh]

The diff looks good. Please make sure to address @chalin's remaining inline comments so that we can merge this.

You can address my other comments in other PRs, and/or maybe create issues, if you want to discuss them first.

[DarikshaAnsari]

@lukpueh and @DarikshaAnsari:

• There should not be a top-nav entry named "Learn more", instead I propose the following.
• Learn-more/faq should be under /docs/faq
• Learn-more/security-audit-23 should be a blog post under a Blog section. Blog should be what appears in the top nav
• Learn-more/news can appear as a News entry in the top-nav

Just to clarify, in my review on slack I didn't mean to re-add the "Learn more" top-nav, but rather to migrate the contents from under the old "Learn more". The structure you suggest for this sounds reasonable. :)

Speaking of my review. @DarikshaAnsari Did you plan to address my other comments as part of this PR? It's okay if not. Just wanted to make sure they are not lost. I'll paste them again here:

• I like that the buttons and links on the landing page navigate to subpages inside docs. Maybe we can make this more consistent. That is, we map all buttons/links on the landing page to subpages . E.g. we could make "demo" and "friends" subpages in docs, to which "Try the demo" and "Explore integrations" point to. Those pages can then contain a short description of demo and friends repos and pointers to those repos. I think that might be a less disruptive experience, compared to when the user is directed to external pages right away on the landing page.
• Why are there two search bars, one in the right top corner and one in the left navigation column? (no need to fix this now, I'm just curious)
• Regarding content I am not sure if we should follow the recommendation from the cncf assessment and just re-publish the docs from python-in-toto as Getting started page. The documentation should represent the whole in-toto project, but the python-in-toto cli is only one of multiple in-toto implementations.

Sure, I have these points in my mind and will open a separate PR for these issues after this PR merges.

[chalin]

Overall, good changes. See inline comments.

One main issue remains regarding the specs page.

What you should have in this PR is the following:

• data/specs.yaml - same as the current site
• layouts/shortcodes/spec-table.md - shortcode that generates the specs table in Markdown; it will be very similar to the current site's layouts/shortcodes/specs.html shortcode, but will use Makrdown instead of HTML in the shortcode. If you can't figure this out, embed the hardcoded table for now and I'll show you how we can do this in a followup PR.
• content/en/docs/specs.md - a page that simply references the shortcode using {{% spec-table %}}.

[DarikshaAnsari]

Overall, good changes. See inline comments.

One main issue remains regarding the specs page.

What you should have in this PR is the following:

• data/specs.yaml - same as the current site
• layouts/shortcodes/spec-table.md - shortcode that generates the specs table in Markdown; it will be very similar to the current site's layouts/shortcodes/specs.html shortcode, but will use Makrdown instead of HTML in the shortcode. If you can't figure this out, embed the hardcoded table for now and I'll show you how we can do this in a followup PR.
• content/en/docs/specs.md - a page that simply references the shortcode using {{% spec-table %}}.

Yes, I have already removed data/specs.yaml, layouts/shortcodes/spec-table.md and use inline markdown table in spec-table.md

[chalin]

Yes, I have already removed data/specs.yaml, layouts/shortcodes/spec-table.md and use inline markdown table in spec-table.md

Clearly there's a misunderstanding. As I mentioned in my review comment, the bulleted list describes what this PR should contain. In the quoted comment of yours above you are confirming that you removed "data/specs.yaml", but it needs to be re-introduced into this PR -- that is, it should not have been removed in the first place. Do you understand what I meant in #7 (review)? If it isn't clear then we can have a video call to clarify. Let me know.

[chalin]

A few more comments, see inline.

[DarikshaAnsari]

If it isn't clear then we can have a video call to clarify. Let me know.

It is clear now. Sorry for the misunderstanding.

[lukpueh]

The diff looks good. Please make sure to address @chalin's remaining inline comments so that we can merge this.

You can address my other comments in other PRs, and/or maybe create issues, if you want to discuss them first.

Still true. :)

[DarikshaAnsari]

@lukpueh Can I merge this PR and start working on other issue, so that there is no conflict.