Markdown Surrounds

Toggles MarkDown elements; bold, italic, and strike-through

---

• ⬆️ Top of Document

• 🏗️ Requirements

• ⚡ Quick Start

  • 💾 Clone
  • ➕ Install
  • 🔥 Uninstall
  • ⬆️ Upgrade
  • 📑 Documentation

• 🧰 Usage

• 🗒 Notes

• 📈 Contributing

  • 🔱 Forking
  • 💱 Sponsor

• 📇 Attribution

• ⚖️ Licensing

---

Requirements

This repository requires the Vim text editor to be installed the source code is available on GitHub -- vim/vim, and most GNU Linux package managers are able to install Vim directly, eg...

• Arch based Operating Systems

sudo packman -Syy

sudo packman -S gawk make vim

• Debian derived Distributions

sudo apt-get update

sudo apt-get install gawk make vim

Note gawk and make are only required if not utilizing a Vim plugin manager.

---

Quick Start

Perhaps as easy as one, 2.0,...

---

Clone

Clone this project...

mkdir -vp ~/git/hub/vim-utilities

cd ~/git/hub/vim-utilities

git clone git@github.com:vim-utilities/markdown-surrounds.git

---

Install

If not using a plugin manager, then this plugin may be installed via make install command...

cd ~/git/hub/vim-utilities/markdown-surrounds

make install

---

Uninstall

If not using a plugin manager, then this plugin may be uninstalled via uninstall Make target...

cd ~/git/hub/vim-utilities/markdown-surrounds

make uninstall

... Which will remove symbolic links and update the Vim help tags file.

---

Upgrade

To update in the future use make upgrade command...

cd ~/git/hub/vim-utilities/markdown-surrounds

make upgrade

---

Documentation

After installation, plugin documentation may be accessed via Vim's :help command, eg...

:help markdown-surrounds.txt

---

Usage

Normal mode default maps are provided for toggling bold, italic, and strike-through state; either for the current word, or line, that the cursor is on.

• <Leader>b toggle bold state of word under cursor.

• <Leader>B toggle bold state of line under cursor.

• <Leader>i toggle italic state of word under cursor.

• <Leader>I toggle italic state of line under cursor.

• <Leader>hi toggle highlight state of current word.

• <Leader>HI toggle highlight state current line.

• <Leader>st toggle strike-through state of current word.

• <Leader>ST toggle strike-through state current line.

---

Notes

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

---

Currently when toggling state of words <cWORD> is used for obtaining the big-word that the cursor is on. This means punctuation and non-letter symbols are included when toggling state. For example toggling bold state of an existing italic word...

Example italic word toggling results

Spam _flavored_ ham

Example bolding italic word toggling results

Spam **_flavored_** ham

... this also means that currently to toggle italic state again requires first toggling bold state, ie. order of operations is outer-to-inner, eg...

Example out-of-order italic toggling results

Spam _**_flavored_**_ ham

... to obtain an un-formatted word from above example would then require the following sequence of commands...

• <Leader>i

Spam **_flavored_** ham

• <Leader>b

Spam _flavored_ ham

• <Leader>i

Spam flavored ham

---

When toggling current line state block-quote, un-ordered lists, and ordered lists are ignored, eg...

Example block-quoted line

> Block quoted line

Example strike-through block-quote

> ~~Block quoted line~~

---

Contributing

Options for contributing to markdown-surrounds and vim-utilities

---

Forking

Start making a Fork of this repository to an account that you have write permissions for.

• Add remote for fork URL. The URL syntax is git@github.com:<NAME>/<REPO>.git...

cd ~/git/hub/vim-utilities/markdown-surrounds

git remote add fork git@github.com:<NAME>/markdown-surrounds.git

• Commit your changes and push to your fork, eg. to fix an issue...

cd ~/git/hub/vim-utilities/markdown-surrounds


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

• Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

---

Sponsor

Thanks for even considering it!

Via Liberapay you may on a repeating basis.

Regardless of if you're able to financially support projects such as markdown-surrounds that vim-utilities maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.

---

Attribution

• :help :map-<buffer>

• :help curly-braces-function-names

• :help fnamemodify()

• :help readfile()

• :help json_decode()

• :help type()

• GitHub -- github-utilities/make-readme

• StackExchange -- Vi -- How can I merge two dictionaries in Vim?

• StackOverflow -- How do I disable the "Press ENTER or type command to continue" prompt in Vim?

• StackOverflow -- Passing a dictionary to a function in viml

---

License

Toggles MarkDown elements; bold, italic, and strike-through
Copyright (C) 2020 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.