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..5c5aa07609a0 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1,4 @@ translations/ includes/ data/release-notes/ +script/bookmarklets/add-pr-links.js 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..6acd7d6310c6 --- /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` + +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` + +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` + +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`. +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` + +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: `dotcom / GHEC / GHES / AE`. (Some of these may get you a "page not found" 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..2934137808e4 --- /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/free-pro-team%40latest%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,%22dotcom%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..e0d7b41ecfa0 --- /dev/null +++ b/script/bookmarklets/pr-link-source.js @@ -0,0 +1,91 @@ +!(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 + } + + const 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 + const parser = new DOMParser() + const doc = parser.parseFromString(html, 'text/html') + + const elements = doc.getElementsByClassName('TimelineItem') + // Find the element that is a link that contains the text "View deployment" + for (let i = 0; i < elements.length; i++) { + const element = elements[i] + const links = element.getElementsByTagName('a') + for (let j = 0; j < links.length; j++) { + const link = links[j] + if (link.innerText.match(/View deployment/)) { + // Get the href of the link + const deployment_url = link.getAttribute('href') + 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(/\/$/, '') + + const url_dotcom = deployment_url + '/en/free-pro-team@latest' + const url_ghec = deployment_url + '/en/enterprise-cloud@latest' + const url_ghes = deployment_url + '/en/enterprise-server@latest' + const url_ae = deployment_url + '/en/github-ae@latest' + const dotcom = 'dotcom' + const ghes = 'GHES' + const ghec = 'GHEC' + const ae = 'AE' + + const file_info = document.querySelectorAll('div.file-info') + for (let i = 0; i < file_info.length; i++) { + let link = file_info[i].querySelector('a').title + if (link.search('data/') === 0) { + continue + } else { + const regex = /\.md$/ + const markdownfile = link.search(regex) >= 0 + if (markdownfile) { + console.log('link: ' + link) + link = link.replace(regex, '') + link = link.replace(/^content/, '') + link = link.replace(/\/index/, '') + let span = document.createElement('SPAN') + span.style.fontFamily = + '-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif' + span.innerHTML = '  View: ' + + span = addLink(span, dotcom, url_dotcom + 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) { + const 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..4bec3b9044c7 --- /dev/null +++ b/script/bookmarklets/view-in-development.js @@ -0,0 +1,3 @@ +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..bef5ee5e99a9 --- /dev/null +++ b/script/bookmarklets/view-in-production.js @@ -0,0 +1,3 @@ +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')