Convert AsciiDoc to Base64

Why Convert AsciiDoc to Base64?

Converting AsciiDoc to Base64 is essential when you need to safely transmit or embed AsciiDoc markup content through text-based protocols, APIs, or data formats that may not handle special characters correctly. AsciiDoc files contain various special characters -- curly braces, brackets, pipes, backslashes, and equal signs -- that can interfere with JSON parsing, URL encoding, or XML processing. Base64 encoding eliminates these issues by representing the entire content as safe ASCII characters.

Base64 encoding converts every byte of your AsciiDoc content into a sequence of characters from a 64-character alphabet (A-Z, a-z, 0-9, +, /), with = padding. This encoding is defined in RFC 4648 and is universally supported across all programming languages and platforms. While the encoded output is approximately 33% larger than the original, this overhead is a worthwhile tradeoff for guaranteed safe transport through any text-based channel.

Common scenarios for AsciiDoc-to-Base64 conversion include embedding documentation content in REST API request bodies (JSON payloads), storing AsciiDoc source in databases that may have character encoding issues, transmitting documentation through email systems (MIME encoding), and creating data URIs for inline content embedding. The encoding is completely lossless -- decoding the Base64 output reproduces the exact original AsciiDoc content.

Developers frequently use Base64 encoding when building documentation pipeline APIs, content management systems, or automated publishing workflows. For example, GitHub's API uses Base64 to transfer file contents, so pushing AsciiDoc files via the GitHub API requires Base64 encoding. Similarly, CI/CD systems often pass documentation content as Base64-encoded environment variables or configuration values.

Key Benefits of Converting AsciiDoc to Base64:

• Safe Transport: No special character issues in JSON, XML, or URLs
• API Integration: Embed AsciiDoc content in REST API payloads
• Lossless Encoding: Perfect round-trip: encode then decode reproduces original
• Universal Support: Every programming language has Base64 support
• Database Storage: Store AsciiDoc in text fields without encoding issues
• Email Transmission: Send AsciiDoc content via MIME-encoded email
• GitHub API: Required format for file content via GitHub's REST API

Practical Examples

Example 1: API Payload Encoding

Input AsciiDoc file (readme.adoc):

= Project README
:toc:

== Overview

This project uses *AsciiDoc* for documentation.

NOTE: See the link:CONTRIBUTING.adoc[contributing guide].

Output Base64 encoded string:

PSBQcm9qZWN0IFJFQURNRQo6dG9jOgoKPT0gT3ZlcnZpZXcK
ClRoaXMgcHJvamVjdCB1c2VzICpBc2NpaURvYyogZm9yIGRv
Y3VtZW50YXRpb24uCgpOT1RFOiBTZWUgdGhlIGxpbms6Q09O
VFJJVVVUSU5HLmFkb2NbY29udHJpYnV0aW5nIGd1aWRlXS4=

Ready for JSON API payload:
{"content": "PSBQcm9qZWN0IFJFQU...","encoding": "base64"}

Example 2: GitHub API File Upload

Input AsciiDoc file (install.adoc):

== Installation

[source,bash]
----
git clone https://github.com/example/repo.git
cd repo
./install.sh
----

WARNING: Requires root permissions.

Output Base64 for GitHub API:

PT0gSW5zdGFsbGF0aW9uCgpbc291cmNlLGJhc2hdCi0tLS0K
Z2l0IGNsb25lIGh0dHBzOi8vZ2l0aHViLmNvbS9leGFtcGxl
L3JlcG8uZ2l0CmNkIHJlcG8KLi9pbnN0YWxsLnNoCi0tLS0K
CldBUk5JTkc6IFJlcXVpcmVzIHJvb3QgcGVybWlzc2lvbnMu

Use in GitHub API PUT request:
PUT /repos/owner/repo/contents/install.adoc

Example 3: Configuration Embedding

Input AsciiDoc file (config-docs.adoc):

= Configuration Reference

|===
| Key | Default | Description
| server.port | 8080 | HTTP port
| db.url | localhost | Database host
|===

Output Base64 for embedding:

PSBDb25maWd1cmF0aW9uIFJlZmVyZW5jZQoKfD09PQp8IEtl
eSB8IERlZmF1bHQgfCBEZXNjcmlwdGlvbgp8IHNlcnZlci5w
b3J0IHwgODA4MCB8IEhUVFAgcG9ydAp8IGRiLnVybCB8IGxv
Y2FsaG9zdCB8IERhdGFiYXNlIGhvc3QKfD09PQ==

Embeddable in YAML config, env vars,
or database text fields without issues.

Frequently Asked Questions (FAQ)

Q: What is Base64 encoding?

A: Base64 is a binary-to-text encoding scheme that represents data using 64 printable ASCII characters (A-Z, a-z, 0-9, +, /). It is defined in RFC 4648 and is used to safely transmit binary or special-character-containing text through channels that only support ASCII. The encoding increases data size by approximately 33%.

Q: Can I decode the Base64 back to the original AsciiDoc?

A: Yes, Base64 encoding is completely reversible and lossless. Decoding the Base64 output will produce the exact original AsciiDoc content, including all markup, special characters, and whitespace. Every programming language provides built-in Base64 decode functions.

Q: Why not just send the AsciiDoc text directly?

A: AsciiDoc contains many special characters (=, *, _, [, ], |, {, }) that can cause parsing issues in JSON, XML, URLs, or other text-based protocols. Base64 encoding eliminates all special character concerns, ensuring the content arrives intact without escaping issues or data corruption.

Q: How much larger is the Base64 output?

A: Base64 encoding increases the data size by approximately 33%. For example, a 10 KB AsciiDoc file will produce approximately 13.3 KB of Base64 output. This overhead is generally acceptable for API payloads and data embedding, but may not be ideal for very large documents.

Q: Is Base64 encryption?

A: No, Base64 is an encoding scheme, not encryption. It provides no security or confidentiality -- anyone can decode Base64 text. It is purely a transport encoding designed to make data safe for text-based channels. For security, use proper encryption (AES, RSA) before or after Base64 encoding.

Q: When would I use Base64-encoded AsciiDoc?

A: Common use cases include: sending AsciiDoc via REST APIs (JSON payloads), uploading files through the GitHub API, storing documentation in databases, embedding content in YAML/TOML configuration files, transmitting via email (MIME), and passing content through CI/CD pipeline variables.

Q: What is the difference between Base64 and Base64url?

A: Standard Base64 uses + and / characters, which are not safe in URLs. Base64url replaces + with - and / with _, making it URL-safe. For most AsciiDoc encoding purposes, standard Base64 is sufficient, but use Base64url if the encoded content will appear in URLs or filenames.

Q: How do I decode Base64 back to AsciiDoc?

A: Use any Base64 decoder: in Python use base64.b64decode(), in JavaScript use atob() or Buffer.from(str, 'base64'), in Java use Base64.getDecoder().decode(), or on the command line use echo "..." | base64 --decode. The decoded output will be your original AsciiDoc content.