gitmd2pdf

Frequently Asked Questions (FAQ)

Would you like to request a feature or have you found an issue that should be fixed? We'd love to hear from you. Use our contact form.

Conversions

What file formats are supported?

Input:

Output:

What markdown features are supported?

We support common Markdown syntax elements, including tables, task lists, and syntax-highlighted code blocks — ensuring accurate Markdown-to-PDF conversion.

What's the maximum file size?

Web UI:

API (Premium):

How is the PDF title chosen if I leave the Title field blank?

The Convert to PDF Title field controls the cover-page title and the downloaded PDF filename. If you fill it in, that wins. If you leave it blank, gitmd2pdf falls back through this order:

Markdown uploads:

  1. The first level‑1 heading (# Heading) in the file (headings inside fenced code blocks are ignored).
  2. The uploaded filename.

Repository conversions:

  1. The top-level title: field in your repository's .gitmd2pdf.yml config, if present (Premium feature).
  2. The repository name parsed from the URL (e.g. https://github.com/user/my-repo.git → my-repo).

In both cases the UI usually pre-fills the Title automatically (from your first # heading for Markdown, or from the repo URL for repositories — the pre-fill does NOT read .gitmd2pdf.yml because the yml lives inside the repo and isn't fetched until conversion runs). You can always edit or clear the field before converting; whatever you leave in it wins over every fallback.

Why does my PDF look different than how my markdown is displayed in .......?

Our PDF renderer may display Markdown differently than other application. Differences can include:

For the most accurate results, use standard Markdown syntax.

Can I convert private repositories?

Yes. You can convert private repositories by providing your Git repository URL along with secure authentication (username and access token) to enable access. See How do I convert a private Git repository? below for the step-by-step flow.

How do I convert a private Git repository? {#private-repos}

Use a Personal Access Token (or whatever your git host calls it — GitHub and Azure DevOps call it a PAT; GitLab calls it a Project Access Token or Deploy Token; Bitbucket calls it a Repository Access Token or App Password). Don't use your account password — most hosts have deprecated password authentication for git over HTTPS, and a scoped PAT is much safer to revoke after the conversion.

Recommended: paste your URL with the username only — the dashboard will prompt for the token

In the Dashboard's Repository tab, paste a URL of the form:

https://YOUR-USERNAME@github.com/your-org/your-repo.git

The form recognises that the host needs authentication and reveals a Personal Access Token field below the URL. Type the token there. Your browser history, server access logs, and any shared error reports won't see the token — the dedicated field is a password input that doesn't autofill or sync.

Alternative: embed the token directly in the URL

You can put the token (or your password, if your host still allows password auth) directly in the URL:

https://YOUR-USERNAME:YOUR-TOKEN@github.com/your-org/your-repo.git

This works but is less safe — the URL itself can leak through browser history, bookmarks, referrer headers, and shared error reports. Use this path when automation already builds URLs of this shape; for interactive use, prefer the username-only URL + dedicated PAT field above.

Security notes

See Git Security for the full provider-specific table (GitHub / GitLab / Bitbucket / Azure DevOps / self-hosted), the API equivalent (repoCredentials body field), and what gitmd2pdf does on your behalf.

My conversion failed with "We hit a problem creating your PDF"

Common causes:

  1. Invalid Markdown syntax: Check your Markdown file for errors
  2. Repository not found: Verify the Git URL is public and accessible
  3. Network timeout: Try again in a few minutes
  4. File too large: Reduce file size or split into smaller conversions

Check conversion_logs in the database for detailed error messages, or contact support with your error details.

Acrobat warns about missing fonts (or fonts look wrong)

This is usually caused by system fonts not being available or not being embedded by the PDF renderer on your platform.

API and Callbacks (Premium Only)

How do I access the API?

Premium users see an API Keys and Callback Credentials section on the Convert to PDF page:

  1. Click "Create New Credential"
  2. Enter a name and choose type (HMAC or OAuth)
  3. Copy your secret (shown only once!)
  4. Use your client ID and secret for API authentication

What's the difference between HMAC and OAuth authentication?

HMAC-SHA256:

OAuth Client-Credentials:

What are the API rate limits?

How do I convert files via API?

Premium API conversions use the same Premium defaults as the Convert to PDF page, including:

Step 1 - Enqueue job:

curl -X POST https://yourapp.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "type=file" \
  -F "file=@data/document.md"

Returns: { jobId: "uuid" }

Step 2 - Poll for completion:

curl https://yourapp.com/api/v1/jobs/JOB_ID/status \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns: { status: "completed", downloadUrl: "..." }

Step 3 - Download PDF:

curl https://yourapp.com/api/v1/jobs/JOB_ID/download \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o output.pdf

How do I convert a Git repository via API?

Use type=repo with a JSON body (OAuth or HMAC):

curl -X POST https://yourapp.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"repo","repoUrl":"https://github.com/iampjeetsingh/nodejs-best-practices","branch":"main"}'

Then poll and download using the same job endpoints shown above.

How do I enable callbacks (webhook delivery)?

Callbacks require an allowlisted domain (exact hostname match). Add at least one domain here:

Then include a callback URL in your conversion request (HTTPS only):

curl -X POST https://yourapp.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "type=file" \
  -F "file=@data/document.md" \
  -F "callbackUrl=https://example.com/webhook"

I upgraded to Premium but don't see the API Keys and Callback Credentials section

Refresh your browser - The UI updates when you reload the page. If you still don't see it:

  1. Log out and log back in
  2. Check your account page shows "PREMIUM_MONTHLY" or "PREMIUM_YEARLY"
  3. If it shows "PRO_MONTHLY" instead, contact support

Subscriptions and Pricing

What plans are available?

We offer three plan levels:

  1. Free Trial - No subscription required, sample the service for 14 days
    • 14-day trial window
    • 6 Markdown file conversions per calendar month
    • 3 Git repository conversions per calendar month
    • No API access
  2. Pro
    • Up to 300 Markdown to PDF conversions per calendar month
    • Up to 50 Git repository to PDF conversions per calendar month
    • No API access
  3. Premium
    • Everything in Pro, plus:
    • Unlimited Markdown and Git repository conversions by default (your account can be capped if usage triggers fair-use review)
    • Public REST API for programmatic conversions
    • HMAC and OAuth 2.0 authentication
    • API credential management

How does the free trial work?

Can I change plans anytime?

Yes. The Convert to PDF and Account pages always show upgrade options for Pro and Premium so you can upgrade or downgrade at any time.

What does my account page show during trial?

When you're on a free trial, your account page displays:

This is user-friendly - the system technically uses a Pro subscription with trial status, but we show "FREE TRIAL" to avoid confusion.

Can I upgrade directly to Premium from a free trial?

Yes! You don't need to upgrade to Pro first. During your trial, you'll see both upgrade options:

Choose the plan that fits your needs. When you upgrade:

  1. Your trial continues to the original end date
  2. If you add a payment method, billing starts after the trial ends
  3. If you chose Premium, you have access to all of the premium features, such as the API Keys and Callback Credentials section appears on your Convert to PDF page

What happens when I upgrade from trial?

After selecting a plan during trial:

If you do not already have a payment method on file, Stripe will prompt you to add one before the upgrade completes.

If I get a free trial, hit my limits, and upgrade to Premium — will I see the Premium features?

Yes! As soon as you upgrade to Premium (even while the trial is still active), the Premium features unlock on your Convert to PDF page. You can continue using the trial until it ends, and billing only starts after the trial ends.

Premium options appear in the right-side Advanced Options panel on the Convert to PDF page.

What happens if I add a payment method during my free trial?

If you add a payment method during your Free Trial, your trial continues until the end date. You will not be charged until the trial ends, and then your paid plan begins automatically.

If you cancel before the trial ends and no payment method is on file, your Free Trial ends immediately and you lose the remaining trial time.

How do I switch between monthly and yearly billing?

Use the "Manage My Subscription" button on your account page. This opens the Stripe billing portal where you can:

What happens when my trial expires?

If you don't add payment details before your trial ends:

Can I cancel my subscription anytime?

Yes!

  1. Click "Manage My Subscription" on your account page
  2. Select "Cancel subscription" in the Stripe portal
  3. Your subscription continues until the end of your current billing period
  4. No refunds for partial months/years (as per standard subscription practice)

Do you store my credit card details?

Under EU law (GDPR), we require explicit consent to store credit card details. When you sign up for a subscription:

Is my payment information secure?

Yes. We use Stripe for all payment processing:

My trial shows "PRO_MONTHLY" instead of "FREE TRIAL"

If you're seeing "PRO_MONTHLY" instead of "FREE TRIAL":

  1. Refresh your browser to load the latest code
  2. Your trial should now show "FREE TRIAL"
  3. The date should show "Trial ends: [date]"

If the issue persists, clear your browser cache or try a different browser.

I can't upgrade during my free trial

Refresh the page - The upgrade buttons should be visible during trial. If you still don't see them:

  1. Check that you're logged in
  2. Verify your trial hasn't expired
  3. Try a different browser or clear your cache

Account Management

Can I use both Social Login and Email login?

Yes. If you lose access to your social account but still have access to the email address, use Forgot your password? and enter that email. You will receive a verification link; follow it to set a password and log in with email.

How do I delete my account?

  1. Log in to your account
  2. Go to the Account page
  3. Scroll to the bottom
  4. Click "Delete Account"
  5. Confirm deletion

What gets deleted:

What you need to do manually:

Can I export my conversion history?

Currently, there's no export feature for conversion history. If you need this functionality, please contact support or file a feature request on our GitHub issues page.

How long is the email verification link valid?

Email verification links expire after 24 hours. If your link is expired or already used, you can resend the verification email from the login screen.

Social Logins

What is "FDR Dev Ley API v2"?

That's Auth0! We use Auth0 for social login integration, which provides:

Can I revoke social login access when I delete my account?

Automatic revocation:

Manual revocation required:

Why? GitHub requires the OAuth app's client credentials to revoke tokens. Auth0's built-in GitHub dev keys don't expose these credentials to our app.

How do I manually revoke GitHub access?

  1. Go to https://github.com/settings/applications
  2. Find "gitmd2pdf" (or the Auth0 app name)
  3. Click "Revoke access"

Contact and Support

How do I contact support?

Click the Contact link in the top navigation menu to access our contact form. You can submit inquiries in the following categories:

Do I need to be logged in to use the contact form?

No! The contact form works for both:

How long does it take to get a response?

We typically respond within 24-48 hours during business days. For urgent issues affecting active subscriptions, we prioritize responses.

Can I attach files to my message?

Currently, the contact form supports text-only messages (up to 5,000 characters). If you need to share files or screenshots:

  1. Upload them to a file-sharing service (Google Drive, Dropbox, etc.)
  2. Include the link in your message

What should I include in a bug report?

When reporting issues, please include:

The more details you provide, the faster we can help!

Still Have Questions?

If you can't find an answer here, use the Contact form in the navigation menu to reach our support team.