Markdown-driven static pages: building the framework #5601

kevinhaube · 2022-05-26T17:56:24Z

This PR adds the framework in to create static pages from Markdown files. This is exemplified by adding in a Built For You example and the Admin > Guides page. Both of these pages are generated by the new framework.

Test Steps:

Login as an admin, and add built-for-you to your feature flags by navigating to Admin > Feature Flags
Refresh the page and ensure you can see Built For You. This means it's successfully hidden behind that feature flag and no end user will see it.
Ensure it works as intended.

Changes

MarkdownDirectory is an object holding markdown files.
StaticPageFromDirectories is a component that takes an array of directories and generates static pages from the markdown content. This also generates side navigation.
DropdownNav is a generative way of adding dropdown navigation items to our header.
Added the /built-for-you route
Added the /admin/guides route
Created the creating-markdown-pages internal user guide

Checklist

Testing

Tested locally?
Ran ./prime test or ./gradlew testSmoke against local Docker ReportStream container?
(For Changes to /frontend-react/...) Ran npm run lint:write?
Added tests?

Process

Are there licensing issues with any new dependencies introduced?
Includes a summary of what a code reviewer should test/verify?
Updated the release notes?
Database changes are submitted as a separate PR?
DevOps team has been notified if PR requires ops support?

Linked Issues

Fixes Web page build - "Built for you: new in Reportstream" #5383

Specific Security-related subjects a reviewer should pay specific attention to

Does this PR introduce new endpoints?
- new endpoint A
- new endpoint B
Does this PR include changes in authentication and/or authorization of existing endpoints?
Does this change introduce new dependencies that need vetting?
Does this change require changes to our infrastructure?
Does logging contain sensitive data?
Does this PR include or remove any sensitive information itself?

If you answered 'yes' to any of the questions above, conduct a detailed Review that addresses at least:

What are the potential security threats and mitigations? Please list the STRIDE threats and how they are mitigated
- Spoofing (faking authenticity)
  - Threat T, which could be achieved by A, is mitigated by M
- Tampering (influence or sabotage the integrity of information, data, or system)
- Repudiation (the ability to dispute the origin or originator of an action)
- Information disclosure (data made available to entities who should not have it)
- Denial of service (make a resource unavailable)
- Elevation of Privilege (reduce restrictions that apply or gain privileges one should not have)
Have you ensured logging does not contain sensitive data?
Have you received any additional approvals needed for this change?

Pull reviewers stats

Stats for the last 30 days:

User	Total reviews	Time to review	Total comments
jeremy-page	24	36m	3
kevinhaube	14	17h 6m	21
carlosfelix2	13	14h 16m	41
TomNUSDS	7	1h 19m	18
clediggins-usds	7	1h 3m	5
bgantick	5	1h 22m	1
brick-green	5	30m	0
ahay-agile6	4	2h 33m	2
mreifman	3	32m	1
oslynn	3	13h 24m	2
jorg3lopez	3	2h 30m	0
MauriceReeves-usds	3	1h 50m	0
sethdarragile6	3	1h 50m	2
TurkeyFried	2	27m	1
cwinters-usds	2	4h 35m	4
JosiahSiegel	1	3m	0
RickHawesUSDS	1	6m	2
snesm	1	10h 44m	0
jh765	1	32m	2

lgtm-com · 2022-05-26T19:22:58Z

This pull request introduces 1 alert when merging 05b017c into 64a1601 - view on LGTM.com

new alerts:

1 for Unused variable, import, function or class

# Conflicts: # frontend-react/src/components/header/AdminDropdownNav.tsx

kevinhaube · 2022-06-01T16:53:18Z

frontend-react/package.json

@@ -63,6 +67,11 @@
        "yarn:show-outdated-packages": "yarn outdated",
        "run-build-dir": "yarn build:localdev:csp && yarn global add serve && serve -s build"
    },
+    "jest": {
+        "transformIgnorePatterns": [


Big ugly line of config to get jest and react-markdown to play nice

ouch! wonder if there's any way to point to this thread for further explanation remarkjs/react-markdown#635 (comment)

doug-s-nava

looks very cool on my first pass! just a few nits here and there. I'm not sure how to test manually, maybe we can run through that tomorrow

doug-s-nava · 2022-06-01T20:40:21Z

frontend-react/package.json

@@ -63,6 +67,11 @@
        "yarn:show-outdated-packages": "yarn outdated",
        "run-build-dir": "yarn build:localdev:csp && yarn global add serve && serve -s build"
    },
+    "jest": {
+        "transformIgnorePatterns": [


ouch! wonder if there's any way to point to this thread for further explanation remarkjs/react-markdown#635 (comment)

doug-s-nava · 2022-06-01T20:43:05Z

frontend-react/src/components/Markdown/MarkdownDirectory.ts

@@ -0,0 +1,22 @@
+/* Used to instantiate a set of static pages, like BuiltForYouIndex


this looks more like a utility class than a component. Maybe it belongs in a utils file somewhere?

I'm on a mission to refactor out the utils files. They tend to become a junk drawer for relatively similar functions a lot of times. That said, I do think it should be either wrapped into a component file or put elsewhere. I think this could easily be merged into the StaticPageFromDirectories code since these are the directories it uses to generate the content. Makes sense to me as a module.

frontend-react/src/components/Markdown/StaticPageFromDirectories.tsx

frontend-react/src/components/header/DropdownNav.tsx

frontend-react/src/content/internal-user-guides/make-markdown-pages.md

doug-s-nava

✅ ✅ ✅ ✅ ✅ ✅ ✅

on the question of where the MarkdownDirectory class should live, I'd still like to see it live somewhere other than Components, since I'd expect everything in there to be renderable as a react component, but that's a personal nit, so this looks good to me to go out as is.

sonarcloud · 2022-06-02T19:49:22Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

80.6% Coverage
0.0% Duplication

kevinhaube added 5 commits May 26, 2022 13:53

Adds useMarkdownDirectory to fetch directory of files as array

fc25891

This test doesn't behave the same every time...

aa4a131

Test runs consisntely, and fails

390d2cf

NOW test fails consistently...

43d1a5d

New direction, no looped fetch

05b017c

kevinhaube added 7 commits May 26, 2022 15:26

Minor fixes

89d1301

Adds generated side nav from directories

8ce17fc

Framework in place for built-for-you static content

48cf243

Fixing what the linter broke

f9e54a9

Breaks out side-nav and adds tests

5b08b2c

Removes duplicate dropdown code for single component

cf4c836

Adding coverage for dropdown nav

fb9cb76

kevinhaube requested a review from aurora-a-k-a-lightning May 31, 2022 20:07

kevinhaube self-assigned this May 31, 2022

kevinhaube added frontend Work Type label to flag work related to the front-end websites experience Team label to flag issues owned by the Experience Team labels May 31, 2022

kevinhaube marked this pull request as ready for review May 31, 2022 20:07

kevinhaube added 2 commits May 31, 2022 16:10

Merge branch 'master' into experience/5383-markdown-static-pages

35b71ac

# Conflicts: # frontend-react/src/components/header/AdminDropdownNav.tsx

Removes old empty file

76330ea

kevinhaube requested review from doug-s-nava and removed request for aurora-a-k-a-lightning May 31, 2022 21:13

kevinhaube added 4 commits May 31, 2022 17:40

Fixes weird nav bug

187b602

Added internal user guide

a835860

Fix up some comments in the code

de796f3

More coverage

6ba518b

kevinhaube commented Jun 1, 2022

View reviewed changes

kevinhaube added 2 commits June 1, 2022 12:56

Merge branch 'master' into experience/5383-markdown-static-pages

bf14101

Fix broken stylesheet

057dbac

doug-s-nava reviewed Jun 1, 2022

View reviewed changes

kevinhaube mentioned this pull request Jun 2, 2022

Add support section with contact and faq pages #5649

Closed

9 tasks

Updates based on PR comments

e5654c3

kevinhaube requested a review from doug-s-nava June 2, 2022 17:01

doug-s-nava approved these changes Jun 2, 2022

View reviewed changes

Merge branch 'master' into experience/5383-markdown-static-pages

ebf2c64

kevinhaube enabled auto-merge (squash) June 2, 2022 19:45

kevinhaube merged commit d6979c4 into master Jun 2, 2022

kevinhaube deleted the experience/5383-markdown-static-pages branch June 2, 2022 19:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Markdown-driven static pages: building the framework #5601

Markdown-driven static pages: building the framework #5601

kevinhaube commented May 26, 2022 •

edited by github-actions bot

lgtm-com bot commented May 26, 2022

kevinhaube Jun 1, 2022

doug-s-nava Jun 1, 2022

doug-s-nava left a comment

doug-s-nava Jun 1, 2022

doug-s-nava Jun 1, 2022

kevinhaube Jun 1, 2022

doug-s-nava left a comment

sonarcloud bot commented Jun 2, 2022

		@@ -0,0 +1,22 @@
		/* Used to instantiate a set of static pages, like BuiltForYouIndex

Markdown-driven static pages: building the framework #5601

Markdown-driven static pages: building the framework #5601

Conversation

kevinhaube commented May 26, 2022 • edited by github-actions bot

Changes

Checklist

Testing

Process

Linked Issues

Specific Security-related subjects a reviewer should pay specific attention to

Pull reviewers stats

lgtm-com bot commented May 26, 2022

kevinhaube Jun 1, 2022

Choose a reason for hiding this comment

doug-s-nava Jun 1, 2022

Choose a reason for hiding this comment

doug-s-nava left a comment

Choose a reason for hiding this comment

doug-s-nava Jun 1, 2022

Choose a reason for hiding this comment

doug-s-nava Jun 1, 2022

Choose a reason for hiding this comment

kevinhaube Jun 1, 2022

Choose a reason for hiding this comment

doug-s-nava left a comment

Choose a reason for hiding this comment

sonarcloud bot commented Jun 2, 2022

kevinhaube commented May 26, 2022 •

edited by github-actions bot