Skip to content

Improve documentation #154

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

Merged
merged 8 commits into from
Nov 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions .github/workflows/pages.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: Build and deploy documentation on GitHub Pages

on:
page_build

permissions:
contents: write

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Add zip file download links to the installation instructions
run: |
RELEASE_TAG=$(git describe --tags --abbrev=0 --match=v*.*.*)
echo $RELEASE_TAG
URL="https://github.com/Stardown-app/Stardown/releases/download/${RELEASE_TAG}/stardown-${RELEASE_TAG}"
echo $URL
cat docs/install-and-update-instructions/script.js \
| sed s,\<a\ class=\"firefox\",\<a\ href=\"$URL-firefox.zip\", \
| sed s,\<a\ class=\"chrome\",\<a\ href=\"$URL-chrome.zip\", \
| tee docs/install-and-update-instructions/script.js >/dev/null
- name: Set up GitHub Pages
id: pages
uses: actions/configure-pages@v5
- name: Build with Jekyll
uses: actions/jekyll-build-pages@v1
with:
source: ./
destination: ./_site
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
deploy:
environment:
name: github-pages
url: ${{steps.deployment.outputs.page_url}}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
2 changes: 1 addition & 1 deletion .github/workflows/release.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Build and release .zip files
name: Build and release zip files

# [softprops/action-gh-release: GitHub Action for creating GitHub Releases](https://github.com/softprops/action-gh-release)
# [GitHub Actions](https://github.com/actions)
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@

<p align="center"><img alt="demo gif" src="https://github.com/Stardown-app/assets/blob/main/Stardown.gif"></p>

* Press `Alt+C` to copy a selection or a page's link.
* Press `Alt+N` to open a notepad that copying with `Alt+C` automatically pastes into.
* Press `Alt+C` (Mac: `⌥+C`) to copy a selection or a page's link.
* Press `Alt+N` (Mac: `⌥+N`) to open a notepad that copying with Stardown automatically pastes into.
* Right-click part of a page to copy it as markdown. Select before right-clicking to copy multiple parts.
* Copy links for all tabs. Select tabs first to copy links for only those tabs.
* Customize these features including keyboard shortcuts in Stardown's settings.
Expand Down Expand Up @@ -54,7 +54,7 @@ Also, please read [./docs/develop.md](docs/develop.md).
Stardown is:

* **Flexible**. Integrates well with many workflows. Select almost anything, copy and paste anywhere.
* **Instantly clip** into a note using Stardown's sidebar notepad to both copy and paste with `Alt+C`.
* **Instantly clip** into a note using Stardown's sidebar notepad to both copy and paste with `Alt+C` (Mac: `⌥+C`).
* **Better at converting**. Stardown's custom code for converting HTML to markdown can convert more formatting than alternatives.
* **Creates [text fragments](https://developer.mozilla.org/en-US/docs/Web/URI/Fragment/Text_fragments)** so you can link to specific parts of pages.
* **Extensible**. Stardown is designed to be extended for more markdown flavors and other markup languages.
7 changes: 4 additions & 3 deletions docs/alternatives.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,14 @@ You can use this [bookmarklet](https://en.wikipedia.org/wiki/Bookmarklet) I made
* [Readwise](https://readwise.io/) can sync highlights from websites, Kindles, iBooks, and more.
* [Roam Highlighter](https://chromewebstore.google.com/detail/roam-highlighter/hponfflfgcjikmehlcdcnpapicnljkkc?pli=1)
* [Zotero](https://www.zotero.org/) is one of the best tools for saving and organizing research.
* [Joplin](https://github.com/laurent22/joplin) has an [official web clipper](https://github.com/laurent22/joplin/blob/dev/readme/apps/clipper.md) of its own.
* [Notion Web Clipper](https://www.notion.so/web-clipper)
* [Evernote Web Clipper](https://evernote.com/features/webclipper)
* [Joplin web clipper](https://github.com/laurent22/joplin/blob/dev/readme/apps/clipper.md)
* [HTML to React & Figma by Magic Patterns](https://chromewebstore.google.com/detail/html-to-react-figma-by-ma/chgehghmhgihgmpmdjpolhkcnhkokdfp)
* [SiYuan](https://github.com/siyuan-note/siyuan) also has an [official web clipper](https://github.com/siyuan-note/siyuan-chrome).
* [SiYuan web clipper](https://github.com/siyuan-note/siyuan-chrome)
* [Send To Logseq](https://chromewebstore.google.com/detail/send-to-logseq/mgdccnefjlmhnfbmlnhddoogimbpmilj) is a browser extension that saves web pages to [Logseq](https://github.com/logseq/logseq?tab=readme-ov-file).
* [github.com/jsartelle/vscode-web-clipper](https://github.com/jsartelle/vscode-web-clipper) is a VS Code extension.
* [github.com/webclipper/web-clipper](https://github.com/webclipper/web-clipper) can integrate directly with Obsidian, Notion, OneNote, Bear, Yuque, Joplin, and more.
* [Obsidian Web Clipper Bookmarklet](https://gist.github.com/kepano/90c05f162c37cf730abb8ff027987ca3) is a bookmarklet for saving web pages directly to Obsidian.
* [Slurp](https://github.com/inhumantsar/slurp) is an Obsidian community plugin and bookmarklet for saving web pages directly to Obsidian.
* [import-github-readme](https://github.com/chasebank87/import-github-readme) is an Obsidian plugin for downloading GitHub readme files directly into Obsidian.

Expand Down
132 changes: 65 additions & 67 deletions docs/install-and-update-instructions/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -71,13 +71,13 @@ <h2>
If in a Chromium browser, select Stardown's <code>chrome</code> folder.
</li>
</ol>
<h2>Install with a .zip file</h2>
<h2>Install with a zip file</h2>
<ol>
<li>
<a href="https://github.com/Stardown-app/Stardown/releases/latest" target="_blank">
Download the .zip file</a> named after your browser
Download the zip file</a> named after your browser
</li>
<li>Unzip the .zip file</li>
<li>Unzip the zip file</li>
<li>
If in Firefox, select the <code>manifest.json</code> file.
If in a Chromium browser, select the folder.
Expand All @@ -90,91 +90,89 @@ <h2>Install with a .zip file</h2>

<form>
<fieldset>
<div class="option">
<input type="radio" id="installing" name="installingOrUpdating" value="installing" checked />
<label for="installing">Install Stardown</label>
</div>

<div class="option">
<input type="radio" id="updating" name="installingOrUpdating" value="updating" />
<label for="updating">Update Stardown</label>
</div>
<ul>
<li>
<input type="radio" id="installing" name="installingOrUpdating" value="installing" checked />
<label for="installing">Install Stardown</label>
</li>
<li>
<input type="radio" id="updating" name="installingOrUpdating" value="updating" />
<label for="updating">Update Stardown</label>
</li>
</ul>
</fieldset>

<fieldset>
<legend>Browser</legend>

<div class="option">
<input type="radio" id="chromium" name="browser" value="chromium" checked />
<label for="chromium">Chromium (Chrome, Edge, Brave, Vivaldi, Opera, Arc, etc.)</label>
</div>

<div class="option">
<input type="radio" id="firefox" name="browser" value="firefox" />
<label for="firefox">Firefox</label>
</div>

<div class="option">
<input type="radio" id="safari" name="browser" value="safari" />
<label for="safari">Safari</label>
</div>
<ul>
<li>
<input type="radio" id="chromium" name="browser" value="chromium" checked />
<label for="chromium">Chromium (Chrome, Edge, Brave, Vivaldi, Opera, Arc, etc.)</label>
</li>
<li>
<input type="radio" id="firefox" name="browser" value="firefox" />
<label for="firefox">Firefox</label>
</li>
<li>
<input type="radio" id="safari" name="browser" value="safari" />
<label for="safari">Safari</label>
</li>
</ul>
</fieldset>

<!-- if updating -->
<fieldset id="installedWith">
<legend>How did you install Stardown?</legend>

<div class="option">
<input type="radio" id="installedWithStore" name="installedWith" value="installedWithStore" />
<label for="installedWithStore">extension store</label>
</div>

<div class="option">
<input type="radio" id="installedWithZip" name="installedWith" value="installedWithZip" />
<label for="installedWithZip">with a .zip file</label>
</div>

<div class="option">
<input type="radio" id="installedWithTerminal" name="installedWith" value="installedWithTerminal" />
<label for="installedWithTerminal">with a terminal</label>
</div>
<ul>
<li>
<input type="radio" id="installedWithStore" name="installedWith" value="installedWithStore" />
<label for="installedWithStore">extension store</label>
</li>
<li>
<input type="radio" id="installedWithZip" name="installedWith" value="installedWithZip" />
<label for="installedWithZip">with a zip file</label>
</li>
<li>
<input type="radio" id="installedWithTerminal" name="installedWith" value="installedWithTerminal" />
<label for="installedWithTerminal">with a terminal</label>
</li>
</ul>
</fieldset>

<!-- if installing -->
<fieldset id="willInstallWith">
<legend>How would you like to install Stardown?</legend>

<div class="option">
<input type="radio" id="willInstallWithStore" name="willInstallWith" value="willInstallWithStore" />
<label for="willInstallWithStore">extension store</label>
</div>

<div class="option">
<input type="radio" id="willInstallWithZip" name="willInstallWith" value="willInstallWithZip" />
<label for="willInstallWithZip">with a .zip file</label>
</div>

<div class="option">
<input type="radio" id="willInstallWithTerminal" name="willInstallWith" value="willInstallWithTerminal" />
<label for="willInstallWithTerminal">with a terminal</label>
</div>
<ul>
<li>
<input type="radio" id="willInstallWithStore" name="willInstallWith" value="willInstallWithStore" />
<label for="willInstallWithStore">extension store</label>
</li>
<li>
<input type="radio" id="willInstallWithZip" name="willInstallWith" value="willInstallWithZip" />
<label for="willInstallWithZip">with a zip file</label>
</li>
<li>
<input type="radio" id="willInstallWithTerminal" name="willInstallWith" value="willInstallWithTerminal" />
<label for="willInstallWithTerminal">with a terminal</label>
</li>
</ul>
</fieldset>

<!-- if installing and using a terminal -->
<fieldset id="hasNodeV14Plus">
<legend>Do you have Node v14+ installed? You can check with <code>node --version</code></legend>
<!-- v14+ because Stardown uses Rollup for bundling, and Rollup uses features
only available in Node v14+. -->

<div class="option">
<input type="radio" id="yesNodeV14Plus" name="hasNodeV14Plus" value="yesNodeV14Plus" />
<label for="yesNodeV14Plus">yes</label>
</div>

<div class="option">
<input type="radio" id="noNodeV14Plus" name="hasNodeV14Plus" value="noNodeV14Plus" />
<label for="noNodeV14Plus">no</label>
</div>
<ul>
<li>
<input type="radio" id="yesNodeV14Plus" name="hasNodeV14Plus" value="yesNodeV14Plus" />
<label for="yesNodeV14Plus">yes</label>
</li>
<li>
<input type="radio" id="noNodeV14Plus" name="hasNodeV14Plus" value="noNodeV14Plus" />
<label for="noNodeV14Plus">no</label>
</li>
</ul>
</fieldset>
</form>

Expand Down
47 changes: 22 additions & 25 deletions docs/install-and-update-instructions/script.js
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,9 @@ safariEl.checked = (
!chromiumEl.checked &&
!firefoxEl.checked
);
if (!chromiumEl.checked && !firefoxEl.checked && !safariEl.checked) {
chromiumEl.checked = true;
}

chromiumEl.addEventListener('change', main);
firefoxEl.addEventListener('change', main);
Expand All @@ -76,19 +79,17 @@ class Instructions {
function main() {
const instructions = new Instructions();

if (chromiumEl.checked || firefoxEl.checked || safariEl.checked) {
if (safariEl.checked) {
instructions.text = 'Safari support coming soon!';
willInstallWithEl.setAttribute('hidden', 'hidden');
installedWithEl.setAttribute('hidden', 'hidden');
hasNodeV14PlusEl.setAttribute('hidden', 'hidden');
} else if (installingEl.checked) {
install(instructions);
} else if (updatingEl.checked) {
update(instructions);
} else {
throw new Error('Neither installing nor updating');
}
if (safariEl.checked) {
instructions.text = 'Safari support coming soon!';
willInstallWithEl.setAttribute('hidden', 'hidden');
installedWithEl.setAttribute('hidden', 'hidden');
hasNodeV14PlusEl.setAttribute('hidden', 'hidden');
} else if (installingEl.checked) {
install(instructions);
} else if (updatingEl.checked) {
update(instructions);
} else {
throw new Error('Neither installing nor updating');
}

if (instructions.text || instructions.steps.length > 0) {
Expand Down Expand Up @@ -159,19 +160,17 @@ function installWithStore(instructions) {
function installWithZip(instructions) {
if (chromiumEl.checked) {
instructions.steps.push(
`<a href="https://github.com/Stardown-app/Stardown/releases/latest" target="_blank">
Download the chrome.zip file</a>`,
'Unzip the .zip file',
'<a class="chrome" target="_blank">Download the zip file</a>',
'Unzip the zip file',
'In your browser, open <code>chrome://extensions/</code>',
'Turn on developer mode',
'Click "Load unpacked"',
'Select the unzipped copy of Stardown',
);
} else if (firefoxEl.checked) {
instructions.steps.push(
`<a href="https://github.com/Stardown-app/Stardown/releases/latest" target="_blank">
Download the firefox.zip file</a>`,
'Unzip the .zip file',
'<a class="firefox" target="_blank">Download the zip file</a>',
'Unzip the zip file',
'In your browser, open <code>about:debugging#/runtime/this-firefox</code>',
'Click "Load Temporary Add-on..."',
'Select the manifest.json in the unzipped copy of Stardown',
Expand Down Expand Up @@ -246,19 +245,17 @@ function updateWithStore(instructions) {
function updateWithZip(instructions) {
if (chromiumEl.checked) {
instructions.steps.push(
`<a href="https://github.com/Stardown-app/Stardown/releases/latest" target="_blank">
Download a new chrome.zip file</a>`,
'Unzip the .zip file',
'<a class="chrome" target="_blank">Download a new zip file</a>',
'Unzip the zip file',
'In your browser, open <code>chrome://extensions/</code>',
'Remove Stardown',
'Click "Load unpacked"',
'Select the newly unzipped copy of Stardown',
);
} else if (firefoxEl.checked) {
instructions.steps.push(
`<a href="https://github.com/Stardown-app/Stardown/releases/latest" target="_blank">
Download a new firefox.zip file</a>`,
'Unzip the .zip file',
'<a class="firefox" target="_blank">Download a new zip file</a>',
'Unzip the zip file',
'In your browser, open <code>about:debugging#/runtime/this-firefox</code>',
'Remove Stardown',
'Click "Load Temporary Add-on..."',
Expand Down
11 changes: 7 additions & 4 deletions docs/install-and-update-instructions/style.css
Original file line number Diff line number Diff line change
Expand Up @@ -36,14 +36,17 @@ fieldset {
margin: 20px;
}

.option {
margin: 5px;
}

#instructions {
margin: 50px;
}

ul {
list-style-type: none;
padding: 0;
margin-top: 5px;
margin-bottom: 5px;
}

li {
line-height: 175%;
}
Expand Down
2 changes: 1 addition & 1 deletion docs/manual-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ When the user right-clicks part of a web page, their browser detects the type of
### Features

- [ ] **Pressing any button in the popup** should do what the button's text describes.
- [ ] **Pressing Alt+C** copies a markdown link for the page, unless part of the page is selected in which case markdown of the selection is copied instead.
- [ ] **Pressing Alt+C (Mac: ⌥+C)** copies a markdown link for the page, unless part of the page is selected in which case markdown of the selection is copied instead.
- [ ] **Right-clicking an empty part of a page** shows the "Copy markdown link for this page" and "Copy markdown link for this section" options.
- [ ] **Right-clicking a website's unselected header** shows the "Copy markdown link for this page" and "Copy markdown link for this section" options.
- [ ] **Right-clicking selected text** shows the "Copy markdown of selection" option.
Expand Down