mdremotifier 1.0.0

Remotify local links in README.md; Make markdown READMEs self contained for publication to sites other than GH, such as npm, pypi.

🎇Features  •  🏠Installation  •  🚜Usage  •  💻CLI  •  💡Examples

✅Requirements  •  🐳Docker  •  🐍Python

CLI to replace ./image.png to raw.githubusercontent.com remote URL in README.md

---

	Status	Stable	Unstable
Master
Develop

---

---

❔ What

What mdremotifier does:

Turn this (./examples/SIMPLE.md):

# Example markdown file

## Local link

[LICENSE.md](./LICENSE.md).

## Local image

![local image](./img.png).

Into this (./examples/SIMPLE.remotified.md):

# Example markdown file

## Local link

[LICENSE.md](https://github.com/realazthat/mdremotifier/blob/master/LICENSE.md).

## Local image

![local image](https://raw.githubusercontent.com/realazthat/mdremotifier/master/img.png).

This is useful for uploading README.md files to third-party sites, like the npmjs.com registry, or pypi.org registry, because these registries will break the local images in your README when displayed on their sites.

See https://pypi.org/project/mdremotifier/, notice how all of the images are not broken.

🎇 Features

• 📷🔗📡🌐🖼️ Replace local URLs with raw.githubusercontent.com URLs.

🏠 Installation

# Install from pypi (https://pypi.org/project/mdremotifier/)
pip install mdremotifier

# Install from git (https://github.com/realazthat/mdremotifier)
pip install git+https://github.com/realazthat/mdremotifier.git@v1.0.0

🚜 Usage

Example README: (./examples/SIMPLE.md):

# Example markdown file

## Local link

[LICENSE.md](./LICENSE.md).

## Local image

![local image](./img.png).

Generating the README:

# Using this command:
# View the template file.
cat "examples/SIMPLE.md"

python -m mdremotifier.cli  \
  -i "examples/SIMPLE.md" \
  --url-prefix https://github.com/realazthat/mdremotifier/blob/master/ \
  --img-url-prefix https://raw.githubusercontent.com/realazthat/mdremotifier/master/ \
  -o "examples/SIMPLE.remotified.md"

# View the remotified file.
cat "examples/SIMPLE.remotified.md"

Result:

# Example markdown file

## Local link

[LICENSE.md](https://github.com/realazthat/mdremotifier/blob/master/LICENSE.md).

## Local image

![local image](https://raw.githubusercontent.com/realazthat/mdremotifier/master/img.png).

Full example:

💻 Command Line Options

💡 Examples

• mdremotifier's own README:
  • Original: ./README.md.
  • Remotified: ./.github/README.remotified.md.
  • Generation script: ./scripts/generate-readme.sh.
• Example:
  • Original: ./examples/SIMPLE.md.
  • Remotified: ./examples/SIMPLE.remotified.md.
  • Generation script: ./examples/simple_example.sh.
• Projects using mdremotifier:
  • realazthat/snipinator.
    • README: snipinator/README.md.
    • Generation script: snipinator/scripts/generate-readme.sh#L29.
    • Remotified: snipinator/README.md.
  • github.com/realazthat/excalidraw-brute-export-cli.
    • README: excalidraw-brute-export-cli/README.md.
    • Generation script: excalidraw-brute-export-cli/scripts/generate-readme.sh#L65.
    • Remotified: excalidraw-brute-export-cli/README.md.

✅ Requirements

• Linux-like environment
  • Why: Uses pexpect.spawn().
• Python 3.8+
  • Why: Some dev dependencies require Python 3.8+.

Tested Platforms

• WSL2 Ubuntu 20.04, Python 3.8.0.
• Ubuntu 20.04, Python 3.8.0, 3.9.0, 3.10.0, 3.11.0, 3.12.0, tested in GitHub Actions workflow (build-and-test.yml).

🐳 Docker Image

Docker images are published to ghcr.io/realazthat/mdremotifier at each tag.

# View the template file.
cat "examples/SIMPLE.md"

# Use the published images at ghcr.io/realazthat/mdremotifier.
# /data in the docker image is the working directory, so paths are simpler.
docker run --rm --tty \
  -v "${PWD}:/data" \
  ghcr.io/realazthat/mdremotifier:v1.0.0  \
  -i "examples/SIMPLE.md" \
  --url-prefix https://github.com/realazthat/mdremotifier/blob/master/ \
  --img-url-prefix https://raw.githubusercontent.com/realazthat/mdremotifier/master/ \
  -o "examples/SIMPLE.remotified.md"

# View the remotified file.
cat "examples/SIMPLE.remotified.md"

If you want to build the image yourself, you can use the Dockerfile in the repository.

docker build -t my-mdremotifier-image .

# View the template file.
cat "examples/SIMPLE.md"

# /data in the docker image is the working directory, so paths are simpler.
docker run --rm --tty \
  -v "${PWD}:/data" \
  my-mdremotifier-image  \
  -i "examples/SIMPLE.md" \
  --url-prefix https://github.com/realazthat/mdremotifier/blob/master/ \
  --img-url-prefix https://raw.githubusercontent.com/realazthat/mdremotifier/master/ \
  -o "examples/SIMPLE.remotified.md"

# View the remotified file.
cat "examples/SIMPLE.remotified.md"

Python Library

If you want to use mdremotifier as a library, you can do so. Here is an example:

from rich.console import Console

from mdremotifier.mdremotifier import Render

md = """
# Example markdown file

## Local link

[LICENSE.md](./LICENSE.md).

## Local image

![local image](./img.png).
"""
url_prefix = 'https://github.com/realazthat/mdremotifier/blob/master/'
img_url_prefix = 'https://raw.githubusercontent.com/realazthat/mdremotifier/master/'

console = Console()
print(
    Render(md=md,
           url_prefix=url_prefix,
           img_url_prefix=img_url_prefix,
           all_references=True,
           console=console))

Here are the API docs:

def Render(*,
           md: str,
           url_prefix: str,
           img_url_prefix: Optional[str] = None,
           all_references: bool = False,
           console: Optional[Console] = None) -> str:
  """ Render the markdown with the given URL prefixes.

  Args:
    md: The markdown string to render.
    url_prefix: The URL prefix to replace the local URLs with. Should probably
      end in a slash.
      Example: "https://github.com/realazthat/mdremotifier/blob/master".
    img_url_prefix: The URL prefix to replace the local URLs with, specifically
      for images. Should probably end in a slash.
      Example: "https://raw.githubusercontent.com/realazthat/mdremotifier/master".
      Defaults to the value of `url_prefix`.
    all_references: Should all references be updated be externalized, or only
      those that are used by links and images? Defaults to False.
    console: The console to print debug information to. Defaults to None.
  """

🤏 Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

🔑 License

This project is licensed under the MIT License - see the ./LICENSE.md file for details.

🙏 Thanks

Main libraries used in mdremotifier are:

• Markdown AST: mistletoe.
• Colorful CLI help: rich-argparse.

🤝 Related Projects

Not complete, and not necessarily up to date. Make a PR (contributions) to insert/modify.

Project	Stars	Last Update	Language	Platform	Similarity X Obviousness
bdashore3/remark-github-images	0	2022/12/29	JS	CLI	⭐⭐⭐⭐⭐
laobie/WriteMarkdownLazily	36	2024/01/06	Python	CLI	⭐⭐⭐⭐
crh19970307/mdul	1	2020/02/01	Python	CLI	⭐⭐⭐⭐
SkyLee424/Go-MarkDown-Image-Transfer-Helper	0	2024/03/25	Go	CLI	⭐⭐⭐⭐
jen6/imgo	0	2020/03/18	Pyhon	CLI	⭐⭐⭐⭐
chocoluffy/lazy-markdown	0	2016/11/20	Python	CLI	⭐⭐⭐⭐
loheagn/gopic	0	2021/11/24	Go	CLI	⭐⭐⭐⭐
Undertone0809/imarkdown	57	2024/01/06	Python	Python	⭐⭐⭐
ravgeetdhillon/markdown-imgur-upload	1	2022/03/26	Python	CLI	⭐⭐⭐

🫡 Contributions

Development environment: Linux-like

• For running pre.sh (Linux-like environment).

  • From ./.github/dependencies.yml, which is used for the GH Action to do a fresh install of everything:

    bash: scripts.
    findutils: scripts.
    grep: tests.
    xxd: tests.
    git: scripts, tests.
    xxhash: scripts (changeguard).
    rsync: out-of-directory test.
    expect: for `unbuffer`, useful to grab and compare ansi color symbols.
    jq: dependency for [yq](https://github.com/kislyuk/yq), which is used to generate
      the README; the README generator needs to use `tomlq` (which is a part of `yq`)
      to query `pyproject.toml`.
    

  • Requires pyenv, or an exact matching version of python as in ./.python-version (which is currently 3.8.0 ).

  • jq, (installation) required for yq, which is itself required for our ./README.md generation, which uses tomlq (from the yq package) to include version strings from ./pyproject.toml.

  • act (to run the GH Action locally):

    • Requires nodejs.
    • Requires Go.
    • docker.

  • Generate animation:

    • docker

  • docker (for building the docker image).

Commit Process

1. (Optionally) Fork the develop branch.
2. Stage your files: git add path/to/file.py.
3. bash ./scripts/pre.sh, this will format, lint, and test the code.
4. git status check if anything changed (generated ./README.md for example), if so, git add the changes, and go back to the previous step.
5. git commit -m "...".
6. Make a PR to develop (or push to develop if you have the rights).

🔄🚀 Release Process

These instructions are for maintainers of the project.

1. In the develop branch, run bash ./scripts/pre.sh to ensure everything is in order.
2. In the develop branch, bump the version in ./pyproject.toml, following semantic versioning principles. Also modify the last_release and last_stable_release in the [tool.mdremotifier-project-metadata] table as appropriate. Run bash ./scripts/pre.sh to ensure everything is in order.
3. In the develop branch, commit these changes with a message like "Prepare release X.Y.Z". (See the contributions section above).
4. Merge the develop branch into the master branch: git checkout master && git merge develop --no-ff.
5. master branch: Tag the release: Create a git tag for the release with git tag -a vX.Y.Z -m "Version X.Y.Z".
6. Publish to PyPI: Publish the release to PyPI with bash ./scripts/deploy-to-pypi.sh.
7. Push to GitHub: Push the commit and tags to GitHub with git push && git push --tags.
8. The --no-ff option adds a commit to the master branch for the merge, so refork the develop branch from the master branch: git checkout develop && git merge master.
9. Push the develop branch to GitHub: git push origin develop.