newrelic / gatsby-theme-newrelic Goto Github PK
View Code? Open in Web Editor NEWSource code for New Relic's Gatsby site theme.
Home Page: https://opensource.newrelic.com/projects/newrelic/gatsby-theme-newrelic
License: Apache License 2.0
Source code for New Relic's Gatsby site theme.
Home Page: https://opensource.newrelic.com/projects/newrelic/gatsby-theme-newrelic
License: Apache License 2.0
We need to instrument our SimpleFeedback
component with NR Browser. We need to track the following events:
feedback_click
: occurs when a user clicks on one of the feedback buttonsProperties that we want to record with this action:
feedback
: whether the feedback is positive or negativeBoth the developer site and the open source site have code blocks rendered on various pages. Let's add the implementation from the developer site.
The docs site will have a "right rail" component that will show a few page-specific items.
The component will look similar to the right rail that appears on the developer site, so we want to abstract it to the theme. This component will continue to utilize its modular architecture to allow for customization of what goes in the right rail. This will also allow site-specific modules that can be used in the right rail.
We also plan to abstract a couple of the common modules that we know are used on all the sites. This includes the contributing module and the last modified module.
NOTE: This is followup of newrelic/docs-website#191 that is specific to the theme work. The docs-site work will be done as a part of newrelic/docs-website#191..
CONTRIBUTING.md
)To comply with our open source standards, lets request a security review of the project to ensure it meets compliance.
To ensure consistency, let's add the hamburger menu so that it can be consumed by all New Relic Gatsby sites.
According to the component audit we will want to use aspects of the design from both the developer website and the open source site.
Design requirements:
Build one Callout component in the theme that takes prop to specify which callout style it should render.
We need to instrument our ExternalLink
and Link
component with NR Browser. We need to track the following events:
externalLink_click
: occurs when a user clicks on any external linkProperties that we want to record with this action:
href
: link clickedCurrently we have branch protection disabled because the opensource bot cannot push to protected branches. @jbeveland27
suggested a workaround that will allow us to enable branch protection and push. This requires us to disable branch protection temporarily, then re-enable once the bot has pushed up changes. This can all be done via GitHub actions.
We need to instrument our ContributingGuidelines
component with NR Browser. We need to track the following events:
editThisPage_click
: occurs when a user clicks on the "edit this page" buttoncreateAnIssue_click
: occurs when a user clicks on the "create an issue" buttonProperties that we want to record with this action:
component
: where this takes place, for this one it would be in page toolsOpening the search overlay by clicking the search icon in the header does not autofocus the input. It would be great to focus the input so that the user can just begin typing their search query without first needing to click on the input.
The input is auto focused after opening the search overlay
We need to instrument our SwiftypeSearch
component with NR Browser. We need to track the following events:
swiftypeSearch_input
: occurs when a user searchesProperties that we want to record with this action:
search_terms
: the text that they inputted when they searchednum_results
: the number of results that came back from the searchWhen using the variant
or similar props for components (such as Button
) we expect the user to supply one of the exported types. That said, sometimes the content creators want to use a component and simply supply a string. In the case of the title
prop for the <Callout>
component, it expects a capitalized string (which is not initially obvious).
We should look through our components and ensure that the user can use an exported type or a string (regardless of casing).
If the repository
is not configured as part of the theme, we should not show any of the GitHub buttons in the footer. This field is currently nullable in the GraphQL schema, but it looks like we do not handle the case where it is null in the footer.
In mobile or narrow viewports, the GlobalHeader
nav is being cut off in the middle of a nav item.
Screen shot from iPhone 8, Safari browser, iOS 13.6.1
Good question! I suppose I'd expect this either:
Since most of the pages using this header will already have their own site-specific hamburger nav, you can probably rule our number 3.
overfill: hidden
rule seems related: https://github.com/newrelic/gatsby-theme-newrelic/blob/develop/packages/gatsby-theme-newrelic/src/components/GlobalHeader.js#L79The site version was displayed in the old OSS site footer, and it was cool but offered no utility and when we tried to apply it to the docs site, it was confusing as it wasn't clear what it was actually communication. So we removed it when we standardize the footer for all sites.
To actually make this useful and warrant it to be present in the global footer it would need to
Based on a recent component audit from @djsauble, there are some similarities between the tile components used on both sites. While the design of the content itself differs, there is an opportunity to extract a base component that provides a container for content like this to live. This component would house the box shadows, background color, border, and text color of the card.
Recommendation: Call this component <Surface />
as this is a surface that sits on top of a background (inspiration from Material design)
Once we have lerna configured in #1 , let's use GitHub actions to automate the release process.
We have buttons defined that can be used across New Relic Gatsby sites, but these buttons do not currently have hover states. We need to define hover states for buttons to better provide the experience that these buttons are interactive.
The Sign Up buttons to create an account should be more explicit relating to what the user is doing on our DECO sites on the Docs site: "Sign Up" makes sense but on the Dev site and OSS Site the button should be "Start Now".
sign up
start now
start now
We need to instrument our GlobalFooter
component with NR Browser. We need to track the following events:
editThisPage_click
: occurs when a user clicks on the "edit this page" buttoncreateAnIssue_click
: occurs when a user clicks on the "create an issue" buttonProperties that we want to record with this action:
component
: where this takes place, for this one it would be in global footerWe have some shared Gatsby configuration that we know we want across all New Relic Gatsby projects. This includes plugins such as gatsby-plugin-newrelic, gatsby-plugin-use-dark-mode, gatsby-plugin-robots-txt, etc. Let's centralize the Gatsby configuration as much as possible and only move what makes sense across all New Relic Gatsby projects.
To comply with our open source standards, let's have the docs team review the README.
Add a custom event into dashboard so we can track stale issues, and how do we track data on stale issue, and time to resolution, etc. Before attempting to implement discuss with the OSS Team and DTK Team if they do this in anyway with Github actions or Git Hub Stats
Like the developer site, let's setup snyk to validate our dependencies.
We need to set up gatsby-plugin-intl
on our gatsby theme or provide a way to render context for the global header and footer, as well as a few other components used by our docs site.
We want to use a consistent color palette across all New Relic Gatsby sites, including dark/light modes. Let's add the CSS variables and colors to ensure consistency.
With the Docs Site we decided to take a streamline approach to have the submit feedback button pass values in the URL using constants, which prevents the need to use a github issue template. This is very streamlined for a user, and it be cool to do this for the developer site as well and be consistent in our approach to creating issues on both sites.
Docs:
https://github.com/newrelic/docs-website/issues/new/choose
Dev Site:
https://github.com/newrelic/developer-website/issues/new/choose
OSS Site
https://github.com/newrelic/opensource-website/issues/new/choose
As noticed in a PR to our developer website, we don't have the best documentation surrounding our global color variables. I wonder if we would be able to link to our color guide / style guide so contributors creating new components are able to reference them!
Both the developer site and the open source site have the ability to show videos on pages. Let's add this component so we can share them between the 2 sites.
According to component audit, we should make the 3D effect used on the open source site toggleable. The design stays the same otherwise.
Let's document configuration options and component APIs so that others looking to use the shared Gatsby theme can do so easily.
We are using normalize.css in the developer site to normalize some cross-browser quirks. Let's provide that out of the box as part of this theme. We can use the polished.js normalize function with emotion to handle this for us.
Like the developer site, we need to generate 3rd party notices to ensure we are using permissively licensed libraries.
To ensure a user cannot discover available pages on our private docs site, we need to ensure sitemaps are not created. Currently the theme is configured to always create a sitemap. We want this to be configurable.
I propose we add a new theme option that will allow us to disable this:
// gatsby-config.js
{
resolve: '@newrelic/gatsby-theme-newrelic'
options: {
sitemap: false
// ...
}
}
To make our package available to our Gatsby sites, we need to publish the package to NPM.
Based on a recent component audit from @djsauble, we will be using the button styles from the Developer Website. Let's add the Button component so we can share it across both websites.
Both the developer site and the open source site should have similar global styles (box sizing, font size, etc). Let's add the shared global styles to this project.
Add the <NewRelicLogo />
that is used in the global header of all sites.
We are using local storage to persist the value on each site. From my googling, it doesn’t look like you can share local storage between subdomains, for security reasons. We’d either have to use cookies (which I think allow you to share across subdomains), or we’d need to implement a common iframe that we can communicate with from each site.
By default, each site uses the user’s OS preference. Unless they’ve specifically switched it, they should have the same theme across the sites.
preferably we'd try and solve it via cookies/local storage so it serves everybody consistently.
We need to instrument our 404 page with NR Browser. We need to track the following events:
404_redirect
: occurs when the user is redirected to the 404 pageProperties that we want to record with this action:
path
: path the user were trying to reachThe SEO component is used both in the OS site and the Dev Site, and likely will be used in the Docs site. We should factor this out into the theme.
We should add prettier and eslint to the project and configure them as needed.
To comply with our open source standards via the open source checklist, let's add an explorer's hub topic and link it in the README.
we will first need to update the NPM Package with details https://github.com/newrelic/gatsby-theme-newrelic
And given we don't have any pre-determined guidance for an npm package.
Will post something similar to what we do with the Nerdpacks which is grab some helpful bits from the README and treat it as an initial "press release" in a sense.
To ensure consistency, we want to add all typography styles to the theme. These include:
We need to instrument our CodeBlock
component with NR Browser. We need to track the following events:
copyCodeBlock_click
: occurs when a user clicks on the "copy" buttonProperties that we want to record with this action:
modified
: whether the code was copied as is or was modifiedWe need to instrument our ResultView
component with NR Browser. We need to track the following events:
swiftypeSearchResult_click
: occurs when a user clicks on a search result linkProperties that we want to record with this action:
href
: link clickedtitle
: title of result clickedNow that we have a public shared theme library, let's highlight it by listing it on our open source website. Documentation can be found on the wiki. You can use the developer website PR as an example.
When we merge PRs into main
, we want to publish a new version of the package to NPM. Using Lerna, we can automate the creation of the changelog, update versions, and publish the package. Note that this will require a manual PR from develop
to main
.
We have search inputs on both sites with similar treatment. Let's add this component so we can share both the implementation and the design.
According to the component audit, we want to use the design from the open source site, but with the added functionality of being able to clear the input with an x
after typing, like on the developer website.
In addition to the designs, let's consider adding a size
prop and allow the component to render as a large
size which will match the size on the open source site
All New Relic Gatsby sites have the same global header. Let's add the global header to this project.
According to the component audit these are the design specs we should be following:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.