feat: add "Edit on GitHub" links to each page #69

lukekarrys · 2022-02-27T00:24:24Z

This setting is part of the theme config. Setting it to true worked
for all pages except cli/**/index.mdx pages which live in this repo
and not npm/cli. This updates the import script to not set per page
github_* config values for index.mdx pages.

Closes #48

npm-docs-robot · 2022-02-27T00:24:48Z

👋 I'm your friendly documentation robot, and I'm going to build your pull request on our staging site so that you can review it. If you push up subsequent commits, I'll rebuild your staging area (and when this pull request is closed, I'll clean that staging area up).

I'll let you know when I'm done! 🤖

npm-docs-robot · 2022-02-27T00:31:42Z

👋 I've finished building this pull request on our staging site. 🤖

To see how it looks, visit: https://docs-staging.npmjs.com/69/

wraithgar · 2022-02-28T15:09:56Z

I still see edit on github on cli pages like https://docs-staging.npmjs.com/69/cli/v8/commands/npm-access

lukekarrys · 2022-02-28T16:11:20Z

This is to add "Edit on GitHub" links to all pages, including npm cli command pages.

Is that an incorrect link on that page to edit that command? I realize that some of it is generated but I think the comments do a good job of pointing people to the correct page. And I would prefer doc PRs that are for generated content if the alternative is no PRs at all.

wraithgar · 2022-02-28T16:38:51Z

I'm on the fence about that. Yes folks could discover through the documentation repo that the cli is the best place to edit those files, I'd just like to set them up for success.

I suppose the real issue is just that: better directing folks who are trying to submit PRs to the documentation repo when the files are sourced from the CLI.

MylesBorins · 2022-02-28T16:59:11Z

Is it possible to not have the edit on github button appear on some pages? For example I don't think we want to expose that option for anything in the policies sections. I also think the edit on github link is giving us the wrong page to edit for any of the index pages such as https://docs-staging.npmjs.com/69/getting-started, as all of those details are in a config file.

I have a similar concern for the the CLI docs, where this is pointing folks towards a place to make doc changes where we can't actually land them (although we can transfer to the CLI repo).

As it is right now I don't think we can land this, would like to ensure we are pointing people to the right place where we have this component

MylesBorins

I want to see the "edit on github" link only appear on pages that can actually be edited in the repository

lukekarrys · 2022-02-28T17:00:20Z

This PR should be pointing people to the cli repo. This is the page I end up on from the access command page: https://github.com/npm/cli/edit/latest/docs/content/commands/npm-access.md

afaict, this page does contain some canonical source for documentation. And the rest is contained in other npm/cli pages that are referenced in comments in that md file.

lukekarrys · 2022-02-28T17:01:25Z

@MylesBorins Do you have a list of pages like policies that I should turn this off on? That should be easy to apply to individual pages.

MylesBorins · 2022-02-28T17:02:46Z

@lukekarrys we should turn this off for the entirety of the policies section and for all index pages. I was mistaken re: CLI changes, great work there 👍🏼

lukekarrys · 2022-02-28T17:05:41Z

I didn’t realize the index pages were generated. I will turn the edit links off on those too.

This also does some the following chores: - Updates to node 16 and npm 8 - Fixes relative urls for published site - Simplifies package.json scripts - Turns on and fixes GitHub edit links ref: npm/documentation#69

This also does some the following chores: - Updates to node 16 and npm 8 - Fixes relative urls for published site - Simplifies package.json scripts - Turns on and fixes GitHub edit links - Uses package.json files to reduce package size ref: npm/documentation#69

This also does some the following chores: - Updates to node 16 and npm 8 - Fixes relative urls for published site - Simplifies package.json scripts - Turns on and fixes GitHub edit links - Uses package.json files to reduce package size - Links packages via workspaces - Installs with only root package lock ref: npm/documentation#69

lukekarrys · 2022-03-01T07:20:38Z

I converted this to a draft PR while waiting on a publish from npm/doctornpm#2 which enables the settings used in this PR.

This adds the "edit on GitHub" links to all pages, except policy pages.
All pages point to their direct counterpart in either this repo or
npm/cli with the following exceptions:

Generated index pages in the /cli/ section point to
npm/cli/edit/<BRANCH>/docs/nav.yml since those contain the section
titles.
The root edit link in the sidebar is removed since it doesn't make
sense to link directly to the homepage of this repo when content is
split across both repos.
index.mdx pages in all other sections are linked to directly since
many of them contain at least some canonical content. I added a
comment to each page in the source indicating that the hierarchical
links in those pages are generated based on src/nav-base.yml.

lukekarrys · 2022-03-01T07:42:28Z

@MylesBorins The only change from what we discussed previously is that I left in the edit links on the index pages, since some of them are not generated. If there are some that we still want to turn off manually, that can still be done.

In this repo they go directly to the index.mdx page which can contain canonical content (eg https://github.com/npm/documentation/blob/main/content/organizations/index.mdx)
For the cli repo they all point to the docs/nav.yml file which is what generates the titles/descriptions. We can't link directly to a line number when editing, but if a user clicks the edit link on a page like this to correct a spelling mistake, it should be fairly obvious where to make the change.

MylesBorins · 2022-03-01T15:59:40Z

@lukekarrys I'm still seeing the edit link on the policy pages FYI (testing staging and locally)

lukekarrys · 2022-03-01T16:04:43Z

Sorry, I should've wrapped this part in 🚨 emojis:

I converted this to a draft PR while waiting on a publish from npm/doctornpm#2 which enables the settings used in this PR.

Can you help me get publish access to that?

This adds the "edit on GitHub" links to all pages, except policy pages. All pages point to their direct counterpart in either this repo or `npm/cli` with the following exceptions: - Generated index pages in the `/cli/` section point to `npm/cli/edit/<BRANCH>/docs/nav.yml` since those contain the section titles. - The root edit link in the sidebar is removed since it doesn't make sense to link directly to the homepage of this repo when content is split across both repos. - `index.mdx` pages in all other sections are linked to directly since many of them contain at least some canonical content. I added a comment to each page in the source indicating that the hierarchical links in those pages are generated based on `src/nav-base.yml`. Closes #48

lukekarrys · 2022-03-01T17:03:49Z

converting back to draft because i broke something

lukekarrys · 2022-03-01T17:37:17Z

@MylesBorins this is ready for review again!

lukekarrys · 2022-03-01T17:38:09Z

cli/cli_import.js

@@ -52,27 +50,6 @@ const cliUrl = '/cli';
 const cliNavFile = path.join('docs', 'nav.yml');
 const cliContentPath = path.join('docs', 'content');

-const indexMarkdown = `<Index depth="1" />`;
-
-const translations = {


These titles are now generated directly from the cli nav: https://github.com/npm/cli/blob/latest/docs/nav.yml#L5

MylesBorins

LGTM

wraithgar approved these changes Feb 28, 2022

View reviewed changes

MylesBorins suggested changes Feb 28, 2022

View reviewed changes

lukekarrys mentioned this pull request Feb 28, 2022

feat: add config to allow hiding github links on individual pages npm/doctornpm#2

Merged

lukekarrys marked this pull request as draft March 1, 2022 04:23

lukekarrys force-pushed the lk/edit-on-gh branch 2 times, most recently from 27ecda5 to ec64875 Compare March 1, 2022 07:19

lukekarrys force-pushed the lk/edit-on-gh branch from ec64875 to dfdc638 Compare March 1, 2022 08:31

lukekarrys force-pushed the lk/edit-on-gh branch from dfdc638 to 6f57364 Compare March 1, 2022 16:54

lukekarrys requested a review from MylesBorins March 1, 2022 16:54

lukekarrys marked this pull request as ready for review March 1, 2022 16:54

lukekarrys marked this pull request as draft March 1, 2022 17:03

fixup! add back path prefix

935d4c7

lukekarrys marked this pull request as ready for review March 1, 2022 17:37

lukekarrys commented Mar 1, 2022

View reviewed changes

MylesBorins approved these changes Mar 1, 2022

View reviewed changes

lukekarrys merged commit 460d30e into main Mar 1, 2022

lukekarrys deleted the lk/edit-on-gh branch March 1, 2022 22:04

feat: add "Edit on GitHub" links to each page #69

feat: add "Edit on GitHub" links to each page #69

Uh oh!

Conversation

lukekarrys commented Feb 27, 2022

Uh oh!

npm-docs-robot commented Feb 27, 2022

Uh oh!

npm-docs-robot commented Feb 27, 2022

Uh oh!

wraithgar commented Feb 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lukekarrys commented Feb 28, 2022

Uh oh!

wraithgar commented Feb 28, 2022

Uh oh!

MylesBorins commented Feb 28, 2022

Uh oh!

MylesBorins left a comment

Choose a reason for hiding this comment

Uh oh!

lukekarrys commented Feb 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lukekarrys commented Feb 28, 2022

Uh oh!

MylesBorins commented Feb 28, 2022

Uh oh!

lukekarrys commented Feb 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lukekarrys commented Mar 1, 2022

Uh oh!

lukekarrys commented Mar 1, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MylesBorins commented Mar 1, 2022

Uh oh!

lukekarrys commented Mar 1, 2022

Uh oh!

lukekarrys commented Mar 1, 2022

Uh oh!

lukekarrys commented Mar 1, 2022

Uh oh!

lukekarrys Mar 1, 2022

Choose a reason for hiding this comment

Uh oh!

MylesBorins left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wraithgar commented Feb 28, 2022 •

edited

Loading

lukekarrys commented Feb 28, 2022 •

edited

Loading

lukekarrys commented Feb 28, 2022 •

edited

Loading

lukekarrys commented Mar 1, 2022 •

edited

Loading