diff --git a/.eslintrc.js b/.eslintrc.js index 6b20dc82b7fc..2e7e063533be 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -13,7 +13,7 @@ module.exports = { babelOptions: { configFile: './.babelrc' }, sourceType: 'module', }, - ignorePatterns: ['tmp/*', '!/.*', '/.next/'], + ignorePatterns: ['tmp/*', '!/.*', '/.next/', 'script/bookmarklets/*'], rules: { 'import/no-extraneous-dependencies': ['error', { packageDir: '.' }], }, diff --git a/.prettierignore b/.prettierignore index 4a66ca51fc5b..a82ea9ebe05a 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1,4 @@ translations/ includes/ data/release-notes/ +script/bookmarklets/ diff --git a/contributing/development.md b/contributing/development.md index 3cd1373b9543..cb06604538b4 100644 --- a/contributing/development.md +++ b/contributing/development.md @@ -48,6 +48,10 @@ This repo has configuration for debugging with VS Code's built-in Node Debugger. For more detailed instructions, please see this [VS Code recipe](https://github.com/Microsoft/vscode-recipes/tree/master/nodemon). You can also learn more about debugging using VS Code [here](https://code.visualstudio.com/docs/editor/debugging). +### Using browser shortcuts + +The [`script/bookmarklets`](../script/bookmarklets) directory contains some browser shortcuts that can help with reviewing GitHub documentation. See [`script/bookmarklets/README.md`](../script/bookmarklets/README.md) for details. + ### Viewing a top-level table of contents While running the local server, you can visit [localhost:4000/dev-toc](http://localhost:4000/dev-toc) to view a top-level TOC of all the content in the site. This page is not available on https://docs.github.com. It was created for internal GitHub writers' use. diff --git a/script/bookmarklets/README.md b/script/bookmarklets/README.md new file mode 100644 index 000000000000..a7f32618db27 --- /dev/null +++ b/script/bookmarklets/README.md @@ -0,0 +1,49 @@ +# Bookmarklets + +The [bookmarklets](https://en.wikipedia.org/wiki/Bookmarklet) in this directory are browser shortcuts that may help with reviewing GitHub documentation. We may eventually build the functionality they provide into Docs preview environments, but these are handy hacks for now. + +## Installing bookmarklets + +For each bookmarklet described below, create a new bookmark in your browser with a descriptive name, open the JavaScript file and copy its contents, and paste the JavaScript _as the bookmark's URL_. + +Clicking the bookmark will then execute the JavaScript. + +⚠️ For Safari, you'll need to do the following: + +1. Go to **Safari** > **Preferences** > **Advanced** and enable **Show Develop menu in menu bar**. +2. Go to **Develop** and enable **Allow JavaScript from Smart Search field**. + +## "View in development" toggle + +[`script/bookmarklets/view-in-development.js`](./view-in-development.js) + +When you're looking at a page on docs.github.com or a preview server at preview.ghdocs.com, clicking this bookmarklet will load the same path you're viewing but on your local server running at localhost:4000. + +## "View in production" toggle + +[`script/bookmarklets/view-in-production.js`](./view-in-production.js) + +When you're looking at a page on a preview server at preview.ghdocs.com or your local server running at localhost:4000, clicking this bookmarklet will load the same path you're viewing but on the live documentation site at docs.github.com. + +## Open a docs article in VS Code + +[`script/bookmarklets/open-in-vscode.js`](./open-in-vscode.js) + +When you're looking at a page on either docs.github.com, preview.ghdocs.com, or localhost:400, clicking this bookmarklet will open the source Markdown file from your local checkout in VS Code. + +The installation requires a few steps: + +1. Copy the contents of [`script/bookmarklets/open-in-vscode.js`](./open-in-vscode.js). +1. Browse to https://chriszarate.github.io/bookmarkleter/ and paste the code into the box. +1. Find the path of **your local checkout** of the docs repo you want to open files from (for example, `/Users//repos/docs`). +1. Paste the path in place of where it says `REPLACE_ME` in line 1 (make sure to leave the single quotes around it). +1. Change the title to something like `Open in VSC`. +1. Drag the generated link onto your bookmarks bar. + +## Add preview links to PRs + +[`script/bookmarklets/add-pr-links.js`](./add-pr-links.js) + +This bookmarklet modifies the `Files changed` page of a GitHub pull request that has a current staging deployment. For each Markdown file in the diff view, it adds links to the preview deployment of the file for each version: `FPT / GHEC / GHES / AE`. (Some of these may redirect to another version or 404 if that version of the page doesn't exist.) + +Note: readable JavaScript source lives in `script/bookmarklets/pr-link-source.js`. The bookmarklet code was generated via https://chriszarate.github.io/bookmarkleter. diff --git a/script/bookmarklets/add-pr-links.js b/script/bookmarklets/add-pr-links.js new file mode 100644 index 000000000000..f71a8ff7d809 --- /dev/null +++ b/script/bookmarklets/add-pr-links.js @@ -0,0 +1 @@ +javascript:void%20function(){!async%20function(){function%20a(a,b,c){var%20d=document.createElement(%22A%22);return%20d.innerHTML=b,d.href=c,d.target=%22_blank%22,a.appendChild(d),a}const%20b=/https:\/\/github.com\/github\/([^\/]*)\/pull\/\d*\/files/;if(!window.location.href.match(b))return%20void%20window.alert(%22You're%20not%20on%20a%20PR%20'Files%20changed'%20page.%20\uD83D\uDE43%22);let%20c=window.location.href.replace(/files.*/g,%22%22),d=await%20fetch(c).then(function(a){return%20a.text()}).then(function(a){for(var%20b=new%20DOMParser,c=b.parseFromString(a,%22text/html%22),d=c.getElementsByClassName(%22TimelineItem%22),e=0;e%3Cd.length;e++)for(var%20f,g=d[e],h=g.getElementsByTagName(%22a%22),k=0;k%3Ch.length;k++)if(f=h[k],f.innerText.match(/View%20deployment/))var%20l=f.getAttribute(%22href%22);return%20l});if(null==d)return%20void%20window.alert(%22No%20preview%20deployment%20found!%20\uD83D\uDE2D%22);d=d.replace(/\/$/,%22%22);var%20e=d+%22/en%22,f=d+%22/en/enterprise-cloud%40latest%22,g=d+%22/en/enterprise-server%40latest%22,h=d+%22/en/github-ae%40latest%22;const%20j=document.querySelectorAll(%22div.file-info%22);for(var%20k,l=0;l%3Cj.length;l++)if(k=j[l].querySelector(%22a%22).title,0===k.search(%22data/%22))continue;else{var%20m=/\.md$/,n=0%3C=k.search(m);if(n){console.log(%22link:%20%22+k),k=k.replace(m,%22%22),k=k.replace(/^content/,%22%22),k=k.replace(/\/index/,%22%22);var%20o=document.createElement(%22SPAN%22);o.style.fontFamily=%22-apple-system,BlinkMacSystemFont,Segoe%20UI,Helvetica,Arial,sans-serif%22,o.innerHTML=%22%26nbsp;%20View:%20%22,o=a(o,%22FPT%22,e+k),o.innerHTML+=%22%20/%20%22,o=a(o,%22GHEC%22,f+k),o.innerHTML+=%22%20/%20%22,o=a(o,%22GHES%22,g+k),o.innerHTML+=%22%20/%20%22,o=a(o,%22AE%22,h+k),j[l].appendChild(o)}}}()}(); diff --git a/script/bookmarklets/open-in-vscode.js b/script/bookmarklets/open-in-vscode.js new file mode 100644 index 000000000000..f49fca3df8c2 --- /dev/null +++ b/script/bookmarklets/open-in-vscode.js @@ -0,0 +1,8 @@ +/* The path to your local copy of repo */ +const checkoutPath = 'REPLACE_ME' + +const filepath = window.location.pathname.replace(/\/en\/([^@]+?@[^@]+?\/)?/, '/content/') +const isIndexFile = filepath.split('/').length < 5 +const filename = isIndexFile ? '/index.md' : '.md' +const fullpath = 'vscode://file' + checkoutPath + filepath + filename +window.open(fullpath, '_blank') diff --git a/script/bookmarklets/pr-link-source.js b/script/bookmarklets/pr-link-source.js new file mode 100644 index 000000000000..cd67aed7271e --- /dev/null +++ b/script/bookmarklets/pr-link-source.js @@ -0,0 +1,92 @@ +!(async function () { + const regexp = /https:\/\/github.com\/github\/([^\/]*)\/pull\/\d*\/files/; + + if (!window.location.href.match(regexp)) { + window.alert("You're not on a PR 'Files changed' page. 🙃"); + return + } + + let conversation_url = window.location.href.replace(/files.*/g, ""); + + // get the preview deployment URL by loading the 'Conversation' page, and searching for the 'View deployment' link + let deployment_url = await fetch(conversation_url) + .then(function (response) { + return response.text(); + }) + .then(function (html) { + // Convert the HTML string into a document object + var parser = new DOMParser(); + var doc = parser.parseFromString(html, "text/html"); + + var elements = doc.getElementsByClassName("TimelineItem"); + // Find the element that is a link that contains the text "View deployment" + for (var i = 0; i < elements.length; i++) { + var element = elements[i]; + var links = element.getElementsByTagName("a"); + for (var j = 0; j < links.length; j++) { + var link = links[j]; + if (link.innerText.match(/View deployment/)) { + // Get the href of the link + var deployment_url = link.getAttribute("href"); + } + } + } + // This should return the last link that contains the text "View deployment" (there might be multiple ones if there are multiple deployments) + return deployment_url; + }); + if (deployment_url == null) { + window.alert("No preview deployment found! 😭"); + return; + } + // strip any trailing slash from deployment_url + deployment_url = deployment_url.replace(/\/$/, ""); + + var url_fpt = deployment_url + "/en"; + var url_ghec = deployment_url + "/en/enterprise-cloud@latest"; + var url_ghes = deployment_url + "/en/enterprise-server@latest"; + var url_ae = deployment_url + "/en/github-ae@latest"; + var fpt = "FPT"; + var ghes = "GHES"; + var ghec = "GHEC"; + var ae = "AE"; + + const file_info = document.querySelectorAll("div.file-info"); + for (var i = 0; i < file_info.length; i++) { + var link = file_info[i].querySelector("a").title; + if (link.search("data/") === 0) { + continue; + } else { + var regex = /\.md$/; + var markdownfile = link.search(regex) >= 0; + if (markdownfile) { + console.log("link: " + link); + link = link.replace(regex, ""); + link = link.replace(/^content/, ""); + link = link.replace(/\/index/, ""); + var span = document.createElement("SPAN"); + span.style.fontFamily = + "-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif"; + span.innerHTML = "  View: "; + + span = addLink(span, fpt, url_fpt + link); + span.innerHTML += " / "; + span = addLink(span, ghec, url_ghec + link); + span.innerHTML += " / "; + span = addLink(span, ghes, url_ghes + link); + span.innerHTML += " / "; + span = addLink(span, ae, url_ae + link); + + file_info[i].appendChild(span); + } + } + } + + function addLink(span, link_name, link_href) { + var anchor = document.createElement("A"); + anchor.innerHTML = link_name; + anchor.href = link_href; + anchor.target = "_blank"; + span.appendChild(anchor); + return span; + } +})(); diff --git a/script/bookmarklets/view-in-development.js b/script/bookmarklets/view-in-development.js new file mode 100644 index 000000000000..025d74eb04d3 --- /dev/null +++ b/script/bookmarklets/view-in-development.js @@ -0,0 +1 @@ +javascript:(()=>{window.location.href=window.location.href.replace(/https:\/\/docs\.github\.com/,'http://localhost:4000').replace(/https:\/\/.*\..*\.(com|net|dev|io|org|ms)/,'http://localhost:4000')})() diff --git a/script/bookmarklets/view-in-production.js b/script/bookmarklets/view-in-production.js new file mode 100644 index 000000000000..a22e139b48cc --- /dev/null +++ b/script/bookmarklets/view-in-production.js @@ -0,0 +1 @@ +javascript:(()=>{window.location.href=window.location.href.replace(/http:\/\/localhost:4000/,'https://docs.github.com').replace(/https:\/\/.*\..*\.(com|net|dev|io|org|ms)/,'https://docs.github.com')})()