From 0b48713a83e75be83fecdae6d6ebea0e98632443 Mon Sep 17 00:00:00 2001 From: Peter Kehl Date: Tue, 15 Aug 2023 06:53:07 +0200 Subject: [PATCH 1/5] Contribution guidelines; moved .vscode/settings.json to settings.json.example; added extensions.json --- .gitignore | 4 +++ .vscode/extensions.json | 9 +++++- .vscode/settings.json | 3 -- .vscode/settings.json.example | 10 ++++++ CONTRIBUTING.md | 60 +++++++++++++++++++++++++++++++++++ 5 files changed, 82 insertions(+), 4 deletions(-) delete mode 100644 .vscode/settings.json create mode 100644 .vscode/settings.json.example create mode 100644 CONTRIBUTING.md diff --git a/.gitignore b/.gitignore index 2e94d4eb..505f0ab7 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,7 @@ pnpm-debug.log* # macOS-specific files .DS_Store + +# Do allow versioning of .vscode/ directory itself, if we want to version some example files or +# extensions.json. +.vscode/settings.json diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 22a15055..f5de56fa 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,4 +1,11 @@ { - "recommendations": ["astro-build.astro-vscode"], + "recommendations": [ + "astro-build.astro-vscode", + "stkb.rewrap", + "bierner.markdown-preview-github-styles", + "davidanson.vscode-markdownlint", + "drmerfy.overtype", + "streetsidesoftware.code-spell-checker" + ], "unwantedRecommendations": [] } diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 97924983..00000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "editor.formatOnSave": false -} \ No newline at end of file diff --git a/.vscode/settings.json.example b/.vscode/settings.json.example new file mode 100644 index 00000000..0c1ba1d8 --- /dev/null +++ b/.vscode/settings.json.example @@ -0,0 +1,10 @@ +{ + "editor.formatOnSave": false, + "editor.rulers": [ + 100 + ], + "markdownlint.config": { + "MD013": false, + "MD025": false + } +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..12ea00c2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# Rules of thumb + +- Leave the last line empty. It makes `git diff` (and any `diff`) easier to review when the last + line is modified/appended. +- Wrap lines. Suggest wrapping to 100 characters, which is the [Rust fmt + standard](https://rust-lang.github.io/rustfmt/?version=master&search=#max_width). + +# VS Code + +If you use VS Code, suggest + +- Do NOT add/commit your `.vscode/settings.json`. Instead, + - add `.vscode/settings.json` (but NOT the whole `.vscde` directory) to `.gitignore`, and + - share any suggested settings in `.vscode/settings.json.example` and add that to git. + +- [Rewrap](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap) for rewrapping comments + and documentation. + + Rewrap doesn't touch the source code itself, only comments (and `.md` files). It preserves + Markdown formatting in comments (even though it understands only one of Markdown + formatting/indentation way of nested lists, see source code of this file below). You can apply + Rewrap to Markdown (`.md`) files, too. + + If you edit existing content a lot, do NOT have Rewrap set to automatic, but use Alt+Q to rewrap + the current comment section (consecutive lines of comments that include the current line). Ctrl+A + Alt+Q rewraps all comments (in the current file). + +- [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) + for Markdown checks. But, suggest turning off + + - [MD013 to allow long lines, for example: Markdown +tables](https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md) + - [MD025 to allow multiple H1 +headings](https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md) + + How? Either by having the following at the top of the `.md` files: + + ```html + + + ``` + + Or by the following user settings. + +- Configure in Ctrl+Shift+P > Preferences: Open User Settings (JSON): + + ```json + "editor.rulers": [ + 100 + ], + "markdownlint.config": { + "MD013": false, + "MD025": false + } + ``` + +- [Code Spell + Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) + +- Please, share other VS Code extensions by adding them to `.vscode/extensions.json`. From 98ada1056ad0128fa17c6c08c2e7e269868138b1 Mon Sep 17 00:00:00 2001 From: Peter Kehl Date: Thu, 17 Aug 2023 04:32:36 +0200 Subject: [PATCH 2/5] Added suggested VS Code extensions --- CONTRIBUTING.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12ea00c2..19b816ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ If you use VS Code, suggest If you edit existing content a lot, do NOT have Rewrap set to automatic, but use Alt+Q to rewrap the current comment section (consecutive lines of comments that include the current line). Ctrl+A Alt+Q rewraps all comments (in the current file). - + - [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) for Markdown checks. But, suggest turning off @@ -57,4 +57,11 @@ headings](https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md) - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) +- [Overtype](https://marketplace.visualstudio.com/items?itemName=drmerfy.overtype) + +- [Markdown Preview Github + Styling](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles) + +- Preview Markdown in a separate tab with `Ctrl + Shift + P` > Markdown: Open Preview. + - Please, share other VS Code extensions by adding them to `.vscode/extensions.json`. From e795878205076e65bff7c924be15eaa6a9684cf8 Mon Sep 17 00:00:00 2001 From: Peter Kehl Date: Thu, 17 Aug 2023 20:42:37 +0200 Subject: [PATCH 3/5] Benefits of using Overtype extension for VS Code --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19b816ed..1836c5a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,7 +57,8 @@ headings](https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md) - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) -- [Overtype](https://marketplace.visualstudio.com/items?itemName=drmerfy.overtype) +- [Overtype](https://marketplace.visualstudio.com/items?itemName=drmerfy.overtype) is excellent when + editing tables, or any preformatted text. - [Markdown Preview Github Styling](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles) From 9d349314d421ed9aa1784d5bb882eac4865f9f3d Mon Sep 17 00:00:00 2001 From: Peter Kehl Date: Thu, 17 Aug 2023 22:08:52 +0200 Subject: [PATCH 4/5] Firefox extension to preview Markdown. --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1836c5a2..98478219 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,3 +66,13 @@ headings](https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md) - Preview Markdown in a separate tab with `Ctrl + Shift + P` > Markdown: Open Preview. - Please, share other VS Code extensions by adding them to `.vscode/extensions.json`. + +# Firefox + +Markdown Preview in VS Code sometimes scrolls the (Markdown) source code up or down. + +For smooth preview, install [Markdown Viewer +Webext](https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer-webext/) in Firefox. Also +configure Firefox [on Linux/Mac +OS](https://github.com/Cimbali/markdown-viewer#support-for-local-files-on-linux-and-macos) so it +applies this extension to local Markdown files. From 45bcf5b9109d794ed501e6494653b40c19e1e1ec Mon Sep 17 00:00:00 2001 From: Peter Kehl Date: Wed, 23 Aug 2023 05:53:46 +0200 Subject: [PATCH 5/5] Previewing Markdown --- CONTRIBUTING.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 98478219..4e5fd45f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,9 +40,7 @@ headings](https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md) ``` - Or by the following user settings. - -- Configure in Ctrl+Shift+P > Preferences: Open User Settings (JSON): + Or configure in Ctrl+Shift+P > Preferences: Open User Settings (JSON): ```json "editor.rulers": [ @@ -64,6 +62,18 @@ headings](https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md) Styling](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles) - Preview Markdown in a separate tab with `Ctrl + Shift + P` > Markdown: Open Preview. +- Unless you're editing a small file, suggest to __disable__ both: + - Settings > Markdown > Preview > Scroll Editor With Preview, and + - Settings > Markdown > Preview > Scroll Preview With Editor. + + Or configure in Ctrl+Shift+P > Preferences: Open User Settings (JSON): + + ```json + "markdown.preview.scrollPreviewWithEditor": false, + "markdown.preview.scrollEditorWithPreview": false + ``` + + And/or preview Markdown in Firefox (see below). - Please, share other VS Code extensions by adding them to `.vscode/extensions.json`.