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

docs: migrate line highlighting to highlight-line, highlight-start, highlight-end #10134

Closed
DSchau opened this issue Nov 26, 2018 · 3 comments · Fixed by #10202
Closed

docs: migrate line highlighting to highlight-line, highlight-start, highlight-end #10134

DSchau opened this issue Nov 26, 2018 · 3 comments · Fixed by #10202
Labels
good first issue Issue that doesn't require previous experience with Gatsby type: documentation An issue or pull request for improving or updating Gatsby's documentation

Comments

@DSchau
Copy link
Contributor

DSchau commented Nov 26, 2018

Summary

Our docs currently use a line highlighting mechanism that is not necessarily ideal. See #9235 for further detail of the general issue. We've since fixed this in #9696, which enables improved functionality that is more maintainable.

Basic example

Given the following (existing) highlighted code snippet, we can re-factor with the changes in this new release.

Note: the following snippet indicates that line 6 is being highlighted, e.g. the plugins array

```javascript{6}
module.exports = {
  siteMetadata: {
    title: `Your Name - Blog`,
    author: `Your Name`,
  },
  plugins: ["gatsby-plugin-catch-links", "gatsby-plugin-react-helmet"],
}
```

to the following new variant

```javascript
module.exports = {
  siteMetadata: {
    title: `Your Name - Blog`,
    author: `Your Name`,
  },
  plugins: ["gatsby-plugin-catch-links", "gatsby-plugin-react-helmet"], // highlight-line
}
```

Motivation

This will be much more maintainable (e.g. resistant to things like prettier messing up line order, code changes, etc.) and a lot easier to use.

Consider using any of the following directives to accomplish this task:

  • highlight-line - highlights the current line
  • highlight-next-line - highlights the next line
  • highlight-start & highlight-end - highlight all lines until highlight-end is encountered

Additionally things like highlight-range are still supported, but I'd recommend using the previously mentioned directives to accomplish this task, as highlight-range does suffer from several of the same issues as the existing functionality.

@DSchau DSchau added type: documentation An issue or pull request for improving or updating Gatsby's documentation good first issue Issue that doesn't require previous experience with Gatsby labels Nov 26, 2018
@DSchau
Copy link
Contributor Author

DSchau commented Nov 26, 2018

Note: for some help in identifying the files:

Consider this regular expression

```(\w+)?\{.+}

this will identify any code fenced blocks with a {} block. I've used it in VSCode like so:

screen shot 2018-11-26 at 9 40 38 am

@nero2009
Copy link
Contributor

Can I take this

@DSchau
Copy link
Contributor Author

DSchau commented Nov 27, 2018

@nero2009 absolutely! I'll mark it as assigned. Looking forward to the PR! Please feel free to reach out to any of us @gatsbyjs/core with any questions!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good first issue Issue that doesn't require previous experience with Gatsby type: documentation An issue or pull request for improving or updating Gatsby's documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants