Git Product home page Git Product logo

doctocat's Introduction

Primer CSS

The CSS implementation of GitHub's Primer Design System

Documentation

⚠️ The documentation of this repo is not maintained anymore. Please raise any documentation-specific pull requests in primer.style/design

Our documentation site lives at primer.style/css. You'll be able to find detailed documentation on getting started, all of the components, our theme, our principles, and more.

Install

This repository is distributed with npm. After installing npm, you can install @primer/css with this command:

npm install --save @primer/css

Usage

The included source files are written in Sass using SCSS syntax. After installing with npm, you can add your project's node_modules directory to your Sass include paths (AKA load paths in Ruby), then import it like this:

@import "@primer/css/index.scss";

You can import individual Primer modules directly from the @primer/css package:

@import "@primer/css/core/index.scss";
@import "@primer/css/product/index.scss";
@import "@primer/css/marketing/index.scss";

Development

See DEVELOP.md for development docs.

Releasing (for GitHub staff)

You can find docs about our release process in RELEASING.md.

License

MIT © GitHub

doctocat's People

Contributors

ashygee avatar binarymuse avatar bolonio avatar camertron avatar colebemis avatar dependabot[bot] avatar dmarcey avatar emilybrick avatar github-actions[bot] avatar hectahertz avatar ichelsea avatar jeffwilcox avatar jfuchs avatar joelhawksley avatar jonrohan avatar josepmartins avatar joshblack avatar joshbowdenconcepts avatar kendallgassner avatar manuelpuyol avatar maximedegreve avatar mperrotti avatar pksjce avatar primer-css avatar rezrah avatar sferadev avatar shawnbot avatar siddharthkp avatar srt32 avatar yaili avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

doctocat's Issues

[Tracking] Docs rebuild

What and why

The current style guide was built to be home to multiple guides yet only Primer CSS documentation is regularly maintained. The current site is built with Jekyll and we stretched it to accommodate multiple sites which has made it difficult to maintain and created a high barrier to contributors. Having the documentation site living in a different repo to Primer CSS code creates some difficulties and makes it inefficient to update and contributes to missing documentation and bugs. Concurrently we re-branded Primer last year to primer.style and have been moving all sites under this domain, so we should do that for Primer CSS to be consistent.

This project will focus on moving the Primer CSS documentation website from https://github.com/github/styleguide/ to http://github.com/primer/primer as a precursor to deprecating the style guide.

Challenges / known issues

  • We are likely to build similar components to those used on Components and other Primer websites which won't feel very DRY, though it's too early to abstract patterns. However, this project will help inform future projects to build a boilerplate for Primer websites.
  • We need to re-think the Primer CSS homepage content and design to work better with the new primer.style website.
  • We're still learning how best to use technologies like Next.js.
  • We only made the style guide public a year ago, we need to make sure the new site is easy to find.
  • We probably have a lot of links to update in other GitHub documentation.
  • We don't have many people we can put on this project full time so Shawn will require support via feedback and code review.

Who

  • @shawnbot will lead the development work.
  • @emplums will provide code review and feedback on docs site build.
  • @broccolini will provide guidance on scope, design, and homepage content.
  • @emilybrick will provide feedback on design and homepage content.

Scope

Tasks are prioritized into Must, Should, Could, and Won't.

Must

These tasks are considered required in order for the project to be successful. They must be completed before publicly shipping the updated documentation site publicly.

  • All documentation ported over (after primer/css#640 merges)
    • Docs
    • Getting Started
    • Principles
    • Tools
    • Remove “What's New” and add nav link called “Releases” and point to releases directly on GitHub.
    • Move “Status key” to “Docs” as level 2 item above “Support”
  • All documentation links such as status, npm packages, and view source should work
  • Code examples should work with correct syntax highlighting
  • Implement search (same or better functionality as current style guide)
  • Responsive navigation, showing top level items (enhancement upon current style guide_)
  • Design
    • Custom illustration for banner
    • Updated homepage styles [tbd @broccolini]
    • Top level nav matches primer.style/components
    • Secondary (left) nav matches current styleguide, but build it better with primer components, and remove status icons
  • Updated homepage content [tbd @broccolini]
  • Re-direct styleguide/primer to new primer.style url

Should

These tasks should be completed for the project to be seen as “done”, but do not need to be completed before making the new site public. These tasks can be addressed in follow-up sprints if not included in the initial ship.

  • Update SCSS principles
    • Remove “Guidelines for using Sass features”
    • Update “Lint rules” and link to Tools > Linting
  • Update contributing Guidelines to match new workflow
  • Update repo to github.com/primer/css to match new site url
  • Update npm to point to @primer/css to match new site url
  • Add notice to style guide homepage that is being deprecated
  • Update references of “Primer” to be “Primer CSS” (where it makes sense to)
  • Design global solution for feedback that works on similar primer documentation sites
  • Deprecate http://styleguide.github.com [tbd @broccolini]
  • Document/capture which components should be abstracted to use across other Primer websites (such as navigation)
  • As far as possible, ensure inbound links are updated to the new url

Could

These tasks are “nice to have's” but not required for project completion. They can be completed adhoc in future Primer releases, though they may be elevated in priority depending on feedback.

  • Add live code editor like Primer Components
  • Update Principles to be more relevant code-style principles
  • Add intro to Tools index
  • Add cross-links to primer.style website
  • Review and update component status

Won't

These items will not be part of the project scope but may be part of future Primer CSS releases.

  • Move new components into Primer that live in GitHub.com
  • Remove Accessibility docs (until Design website is live)
  • Build reusable components to use across similar Primer websites.
  • Design a solution for navigating between different Primer websites.

[Component] Metadata / References

How can we display references and other "related-links" metadata?

Goals:

  • Help visibility and discoverability of guidelines for the same component
  • Avoid duplication of content

Examples of related links:

  • Interface guidelines doc
  • CSS doc
  • React components doc
  • Figma file
  • Code in GitHub

[Feature request] Disable soft-wrap for live examples

It seems that live examples soft-wrap the code blocks. Should soft-wrapping be disabled, like non-live code blocks?

Benefits

It would allow long lines of code take up less space. For example we could show svgs of octicons that currently look like this:

image

... as a single line:

<button class="SelectMenu-closeButton" type="button">
  <!-- <%= octicon "x" %> -->
  <svg width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48L7.48 8z" /></svg> 
</button>

Making it easier to read the rest of the code. It's still possible to horizontally scroll if needed. Or manually add line breaks to the example if something is important enough to not be hidden behind the overflow scrolling.

Gatsby warns about global graphql

Just saw this running npm start over in primer/css:

warn Using the global `graphql` tag is deprecated, and will not be supported in v3.
Import it instead like:  import { graphql } from 'gatsby' in file:
./docs/node_modules/@primer/gatsby-theme-doctocat/src/components/search.js

Not a big issue, but something we'll probably want to fix up so that a future transition to Gatsby v3 will be smoother.

Live Preview Z Index

@taleymirza noticed over in primer/react#587 that content in the live editors are overlaying the header - we should either increase the z-index of the header or set the z-index of the live code editor to 0 (or both??)

Doctocat User Feedback

  • Migrating to Doctocat

I think we should have a specific section for migration to using Doctocat from another docs framework. This would generally mean documentation on using Doctocat inside of another repository. This was hinted at a bit in the docs but was a little hard to find/follow.

It's not clear in these docs whether my-site is referring to the root name of your site, or the name of the folder that your docs live in

  • If you want to create a new site in an existing repository, be sure to run the gatsby new command from within that repository.

This doesn't make it clear what arguments I should run with gatsby new if i have an existing repository, and where in that repo I should run it. Let's change this code snippet to the full command.

This doc should go through all the steps of setting up a site, similar to the Getting Started doc

  • Let's be clear that you can name your site folder anything you'd like. We can provide naming guidance here if necessary.

  • We need to mention that the content folder needs to be named content for Reasons.

  • Let's add docs on where to put local components if you need to build them and how to import them and use them in an MDX - write this for the audience of people who might not have a ton of React experience

  • 404 page missing

  • Clicking on an item while scrolled down in the sidenav scrolls back up when the page changes, which is kind of annoying if you are clicking through items in the sidenav one by one

  • Ran into some issues with the template putting a now.json in the docs folder, but needing to actually have it in the root. This has got me thinking that it is kind of confusing to have two pretty different ways of setting up a Doctocat site - within a subdirectory, or in the root and how different those setups end up being 🤔 I'm not sure what the solution is because I know this is due to limitations with template repos but wanted to mention it.

Add caption component

It would be useful to include a caption component. We use captions in the "Do/Don't" component, but also underneath regular images.

Currently, it looks like this:
Screenshot 2019-08-16 14 56 22

Proposed:
Screenshot 2019-08-16 14 56 49

Styling to achieve ☝️:
<Text fontSize="0" color="gray.5">Fold/Unfold Icon used in Profiles context</Text>

Focus-lock causing issues with dialogs/overlays

Problem

Implementing doctocat in @primer/components, I noticed that the focus-lock library seems to be interfering with any dialog or overlay on the page.

The first issue I noticed was with the Dialog component docs - when clicking on the open button, focus-lock throws an error and the dialog doesn't open. More details in my comment here: theKashey/focus-lock#11 (comment)

I also noticed that in the last Details example and the Dropdown component docs, I can click to open the elements, but afterwards any additional clicks should close the dialogs but they do nothing.

I'm not 100% sure that focus-lock is the culprit for the last two examples, but I have a strong feeling it is.

Solutions

  • Attempt to use the whitelist API from focus-lock to only target necessary elements on the page
  • Remove focus-lock all together and use an alternative solution (@colebemis mentioned focus-lock is probably our best bet though)
  • Alternative JS solution I haven't thought of yet!

New component: Access old versions

From @broccolini in https://github.com/github/design-systems/issues/907:

Can we link to previous versions of our docs sites? I'm not sure how long we are keeping old branches, but after a quick look we do have the last several versions on Primer CSS and Octicons. Could we make this easier to find publicly? Occasionally people want to access the old docs for a previous version since they are not ready to upgrade yet, so this can be very helpful, particularly with big updates like we've just shipped.

Example of release urls:

https://primer-css-git-release-1300.primer.now.sh/css/
https://primer-css-git-release-1400.primer.now.sh/css/
https://octicons-git-release-960.primer.now.sh/octicons/
cc @emplums @BinaryMuse @colebemis

Links in primer global nav

To ensure people find all the things, I think we should cross-link to related documentation sites where needed. Some things aren't ready yet but I wanted to capture what I was thinking should go in each of the dropdowns.

Design 🔽

Title Link Status
Interface guidelines https://primer.style/design
Octicons https://octicons.github.com
Prototyping https://primer.style/css/tools/prototyping
Presentations https://primer.style/presentations
Email https://primer.style/email Not shipped
Illustration https://primer.style/illustration Not transferred
Brand https://brand.github.com
Logos https://github.com/logos

Questions:

  • should we differentiate links that aren't in the primer.style domain? Perhaps with ➡️ icon or something?
  • how should this be ordered? alphabetical or something else?
  • do these feel like the right links in the right section?

Development 🔽

Title Link Status
Primer CSS https://primer.style/design
Primer Components https://octicons.github.com
Email build tool https://github.com/github/email-build-tool

(In future we might want to cross-link to other dev documentation like web systems but I think this is good for now.)

Question: Since the email build tool is only accessible to staff, should we add a 🔒icon or something on that and other private links?

Content

Title Link Status
Content https://primer.style/content Not transferred

About

In future I think we can flesh out more detail under "about", something like this:

  • Who can use Primer? (Link to About page and explain usage)
  • Team (link to About page team profiles section)
  • Open-source (links to primer org)
  • Contributing
    • Design and code contribution guidelines for all parts of our design system
    • Guidelines for how to build, customize, and maintain Primer documentation websites (perhaps this links to primer.style/doctocat ?)

What's New

Once the updates to primer.style are completed (homepage and the news feed), I think we could make it easier to jump to releases etc.:

  • Releases / changelog (should we have a global changelog?)
  • Posts (articles, talks, podcasts, interviews)

Feedback welcome!

cc @primer/ds-core

[Component] Alert

How can we draw attention to specific content? Currently, in most instances we have bold text before the paragraph:

Screenshot 2020-01-28 at 14 26 33

Used keywords: Note (4x), Attention (4x), Usage warning, Important

Could we reuse the styles from existing alerts or toasts? Also: box.

LICENSE file?

Hi,
I was wondering how this project is licensed?

I'd love a LICENSE file in the root and also a license property in the package.json... happy to add these assets if there's a known license for Primer or Doctocat that the maintainers agree on.

(I'm looking to egregiously borrow some of the doctocat theme components in adapting my own Primer theme for an internal MSFT resource)

Create templates for index pages

Some section divider pages (e.g. https://primer.style/css/objects and https://primer.style/design/ui-patterns) are empty or almost empty. We could use these pages to provide an overview of the content within the section.

The template should be flexible to cater for different types of content. If the section has content that can be represented visually (example: components), we could use icons. If it's more text or code based, we could show relevant snippets or text.

Update: Include also landing pages, e.g. https://primer.style/design/

Examples:

Hot reloading breaks for @primer/gatsby-theme-doctocat

It looks like hot reloading breaks for MDX files processed with @primer/gatsby-theme-doctocat. When I make edits in an MDX file, I see this error message:

Screen Shot 2020-06-14 at 4 21 34 PM

Sometimes this error happens upon first edit and hot reloading attempt, sometimes upon second edit and hot reloading attempt. I can see with the debugger that when the error occurs some props of the frontmatter of the pageContext passed into the generated page are missing, even though they are present in the MDX file.

You can reproduce this issue with this repository:

https://github.com/UNDataForum/design-system/tree/695cbb3233e3f441572aa484c48248c4b7edcc02

Run yarn workspace docs run dev to launch the dev server. Edit one MDX file, eg, docs/content/components/event-preview.mdx. Make a simple edit in the text and save. You should see the error from above screenshot.

Use gatsby-plugin-catch-links

This plugin intercepts all local links that have not been created in React using gatsby-link, and replaces their behavior with that of the gatsby-link navigate. This avoids the browser having to refresh the whole page when navigating between local pages, preserving the Single Page Application (SPA) feel.

Check out the gatsby-plugin-catch-links docs for more information.

live-code-preview doesn't bring sass styles

Howdy

First of all, I am stoked with doctocat. We are moving from storybook at Thinkific and your theme is so cool. Never worked with Gatsby before and it has been a great developer experience.

We have a component library in React. Our components use SASS. I am trying different things here with the jsx live and I am not sure if this use case is mapped:

I have created a live-code-scope.js following your docs:

import Badge from '../../components/Badge';
export default { Badge };

In my badge.mdx file I have:

<Badge type="primary">Primary</Badge>

The output of the code will be:

<span class="badge badge--primary">Primary</span>

...but the styles are not there.

Tried a different approach: added an import in my mdx file (and the gatsby-plugin-sass plugin). This time the CSS works fine inside the mdx file, but not inside the jsx live block (reference error as covered in your docs). In details:

import Badge from 'src/components/Badge'
<Badge type="primary">Primary</Badge>

jsx
<Badge type="primary">Primary</Badge>

Any ideas of what is going on here?

Thanks and keep being awesome

Implement live editor

Do this

  • Implement a live editor similar to the one used in the Primer CSS and Primer Components documentation sites

Examples

Primer Components

image

Primer CSS

image

Table of Contents Feedback

I noticed that for long tables of contents scrollbars show up - could we remove these?

image

I also wonder if the TOC should line up with the title instead of the first paragraph under the title? https://share.getcloudapp.com/RBuveZw4

the live editors now are feeling a little narrow. Would it make sense to remove some of the padding to the left of the main content area to allow the live editors a bit more space? https://share.getcloudapp.com/NQuDLjed

related: the copy button in live editors overlays the text inside the editor. This was always happening but is more noticable now that the editors are more narrow. Could we make it so that the copy button never overlaps the code? https://share.getcloudapp.com/4guyweyG

Make it more obvious that you can type in live code examples

Problem

Be able to type in the code examples is such a nice feature but it's hard to discover.

circle

Possible solution

  • Mention it somewhere.
  • Have an 🖊 "edit" button. Maybe next to the "copy code" button. Clicking it would focus the editor. Clicking the button isn't necessary, but it would make it more clear that the code can be edited.

‘Add a primer.style path alias’

In Add a primer.style path alias and https://primer.style/doctocat/usage/deployment#4-update-nowjson-in-primerprimerstyle, I read this: after the configuration, I can open a pull request within the format; once approved, my own docs site can be access under https://primer.style/my-site

While I understand you just made this repository public, which is very kind for the benefic of the open source community, but should the statement above be true to everyone so that the public can let you host thier docs sites, or it's just a internal thing that it's just the documentation haven't been updated soon enough?

Many thanks for any potential answers :D

Fix mobile navigation in macOS Safari

Problem

In macOS Safari, clicking links below the fold in the responsive navigation drawer causes focus to jump to the first link instead of going the destination of the link.

Here's a codesandbox that reproduces the issue: https://codesandbox.io/s/responsive-navigation-safari-bug-6hvj4

Notes

  • Removing the FocusLock component from the Drawer component fixes this issue.

  • Removing tabIndex="-1" from the wrapper div created by @reach/router also fixes this issue:

    image

New Table of Contents

@yaili and I have been working through some new iterations for components in our docs! One of the items that we'll need to build out is a new table of contents. Instead of having the table of contents take up a large portion of the main content area, we are moving the TOC to a sidebar.

Requirements

  • TOC is automatically generated from the headings on the page. You can access the table of contents via pageContext. I think this is something that MDX provides and we access via graphql in gatsby-node.js)
  • Should be position: sticky

Screenshot

image

Figma

Figma file See frame 16.

For now the first iteration, let's just focus on getting the table of contents into the sidenav, but in the future we'll also want to append a "references" section below the table of contents.

Open Questions

  • @yaili In the latest Figma frame, I see that there is a yellow bar beside one of the table of content items. Should this show up only when the URL matches that section (this would only happen when someone clicks on a link in the table of contents, clicks on a heading, or comes directly to a URL that references one of the headings in the page), or should that bar update as the user scrolls through the page?

Keeping Everything Fresh 🌱

Doctocat is starting to get a fair amount of traction! 🎉 This is wonderful news, and leads me to think we need to start defining some processes for keeping everything up to date and if possible, automating this process.

Goals

  • primer/doctocat should always have the latest version of Primer React Components and Primer Octicons
  • primer/dotocat-template should always be using the latest version of the doctocat theme
  • All of our documentation sites should be using the latest version of the doctocat theme

Roadblocks

  • Keeping all of these up to date is time consuming. Take for example shipping a new version of Primer Components. Afterwards, we'd need to update the version in primer/doctocat, which would mean we'd need to ship a new release. Then we'd need to update each of our doc sites (I believe we're up to 10+ doc sites at the moment), and the primer/doctocat-template repository with the new doctocat theme verison.

Because this is so tedious, we don't often do it 😬 Many of the docs sites are currently using old versions of doctocat, and the doctocat template is using a version of the doctocat theme that is 12 versions old 😬

Potential solutions

  • Could we use a GitHub Action that automatically creates a new PR for all our docs sites when primer/doctocat ships a new version?
  • Could dependabot do this for us?
  • If there isn't an easy way to automate this, would it make sense to schedule a recurring time to do this manually once a month?

Whitespace gets removed in live code examples

When using the following example in a live code example:

<input type="checkbox" checked>
Label

The example shows no white space between input and text:

Screen Shot 2019-12-30 at 5 55 44 PM

Is this some sort of config that could be changed? On dotcom or CodePen for example, the DevTools adds a line break after the ":

"
Label
"
Doctocat CodePen
Screen Shot 2019-12-30 at 6 02 53 PM Screen Shot 2019-12-30 at 6 02 00 PM

Markdown styles

Do this

  • Style the markdown content area to use GitHub's markdown styles
    • Explore an implementation that uses @primer/css/markdown
    • Explore an implementation that uses React components and MDXProvider

Hidden overflow on live editors

The overflow: hidden on live editors is causing some issues for content that would ideally overlap:
image

It also messes up the <Sticky> example and causes the sticky element to scroll past the container div.

@colebemis is there any context around why this was needed?

RFC: Naming guides

Problem

As I've been writing documentation guides for Doctcat, I've noticed that the way we've named the guides is slightly inconsistent. Here's how the navigation is currently structured:

- Getting started
- Guides
  - Gatsby CLI
  - Side navigation
  - Adding a hero
  - Creating live previews
  - Changing the favicon
  - Deployment
- Theme options
- Components
- Contributing

Some guides start with a present participle (e.g. "Changing the favicon," "Creating live previews") and some don't (e.g. "Gatsby CLI," "Deployment"). I think now is a good time to discuss some guidelines around naming guides and navigation links in general.

Questions

  • What should we name the Doctocat guides? Is it okay to use a present participle in some guide titles and not in others?
  • More generally, how should we organize the navigation? Do we need a "Guides" category? Should the documents under "Guides" be reorganized?

Goal

The goal of this issue is to settle on an structure for the side navigation of the Doctocat documentation site that is consistent and clear.

References

Here are a few documentation sites I've used as "inspiration:"

Headers in left-side navigation don't have any link affordances

I learned today that the headings in the left-side nav can be clicked.

image

If you don't casually roll over one of these, I think it's pretty difficult to know it's a link, as there are none of the standard hints that the element is clickable.

On Primer Components, we're considering simply removing those links and make the pages they link to more visible in the navigation: primer/react#786

Component container hiding content

I'm not sure if this the right place for this issue, but I've noticed that the component container can sometimes hide content depending on positioning styles (rather than growing the height of the container for the component)

Example:
Screenshot 2019-08-12 16 44 48

On the deprecated styleguide site, this doesn't seem to be an issue: https://styleguide.github.com/primer/components/subhead/

@simurai got around this by adding a fixed height to this toast example
Screenshot 2019-08-12 16 55 48

https://primer.style/css/components/toasts

Implement responsive search

Problem

The search input doesn't appear at small viewport sizes on Doctocat sites:

image

Do this

  • Add a search input for smaller viewports that works like the search input on the old styleguide:

Kapture 2019-08-22 at 9 00 54

Shadowing the header.js requires to shadow most of /components/ to work

Hi there,

Thank you so much for making this available publicly.

I'm building a gatsby site for our company's docs and I'm using doctocat. My only pet peeve is that shadowing header.js requires to shadow almost all of the files /components as well as use-search.js and I feel it's making the whole point of gatsby-themes useless in this case.

Is there a better way to proceed to customize the header component? (basically removing the GitHub logo and Primer).

Thanks in advance!

Support sandboxed code examples

In the Primer CSS docs we need the ability to sandbox code examples from the enclosing document. Additionally, it would be nice to be able to import JS into each sandbox without it being loaded in the top-level document. For instance, in our MDX component mapping for Primer CSS, it would be great to be able to do something like:

const components = {
  pre: ({children, ...rest}) => (
    <CodeExample {...rest}>
      {children}
      <script src="https://unpkg.com/@primer/[email protected]/dist/index.umd.js" />
    </CodeExample>
  )
}

Or, even better, to be able to import it via webpack's file-loader and reference it via the bundled URL so that we don't have to hit unpkg and can version it in package.json:

// see: https://webpack.js.org/concepts/loaders/#inline
import gOction from '!!file-loader?modules!g-octicon'
import primerCSS from '!!file-loader?modules!@primer/css/dist/primer.css'

const components = {
  pre: ({children, ...rest}) => (
    <CodeExample {...rest}>
      <link rel="stylesheet" href={primerCSS} />
      {children}
      <script src={gOction} />
    </CodeExample>
  )
}

I suppose that if we're using iframes it would be nice to support a prop for these, e.g. an array of assets would be translated into a <head> element with the appropriate <link> and <script> tags:

const components = {
  pre: props => <CodeExample {...props} assets=[gOcticon, primerCSS]} />
}

Maybe it would only be rendered as an iframe if there were assets that need to be sandboxed? 🤔

Add "Skip to main content" link

Should we add a "Skip to main content" link to Doctocat that allows a keyboard-only user the ability to navigate directly to the page's content and bypass all of the navigation tab stops?

https://webaim.org/techniques/skipnav/

I was thinking of something similar to docs for gatsbyjs: https://www.gatsbyjs.org/docs/mdx/writing-pages/ (load the page and hit tab to see the example).

Something like the following as a starting point:

Screenshot showing a Skip to main content link on the Doctocat page

Let me know if we would want something like this to be added to the doctocat theme and I can at least work on wiring up the functionality and then solicit feedback on design of the link.

Primer documentation workshop (9/3/2019)

Logistics

The workshop is scheduled for next Tuesday (9/3) 1:30-3pm PST with adrianmg, ampinsk, and gladwearefriends.

Goals

  • Get designers excited about contributing to Primer documentation sites.
  • Learn how we can improve the contribution workflow.

Agenda

  • Go over the agenda and goals for the workshop.
  • Explain the file structure of a Primer documentation site (e.g. content/, nav.yml, gatsby-config.js).
  • Walkthrough adding the process of adding new page to Primer Interface Guidelines to demonstrate the contribution workflow.
    • This will teach topics like:
      • Running the documentation site locally
      • Adding a new link to nav.yml
      • Writing front matter
      • Importing components into markdown files
      • Writing live code examples
      • Deploy previews
  • Have designers make real (but small) contributions to Primer Interface Guidelines. These contributions should be coordinated ahead of time.
  • Ask designers to give feedback on what went well and what could be improved in the contribution workflow.

Preworkshop checklist

  • Have attendees think about a small contribution they want to make to https://primer.style
  • Check that attendees have Node.js and npm set up on their machine

Table of Contents Design

Should we consider updating the table of contents design?

image

Something about it feels a little jarring to me in this context 🤔

Focus color mobile

On mobile when you click the nav menu and close it then the color of ThreeBarsIcon stays same as hover color until you focus somewhere else. Is there a way to fix it?

CECB472A-8451-4D73-A5C5-9B0D6168CF3E

Originally primer/react#837

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.