If your Rails page looks correct in a browser but its Wicked PDF output loses CSS, diagnose two separate problems: whether wkhtmltopdf can retrieve the stylesheet and whether it is rendering with the media rules your CSS expects. Wicked PDF runs the external wkhtmltopdf program, not the browser session that served your Rails page, so relative asset URLs, pipeline files, authentication, and deployment networking can all change the result.
Work through the checks below in order. First prove the generated HTML contains reachable CSS, then fix Rails 3 asset handling, then select print media if required.
Why browser CSS disappears from a Wicked PDF
Wicked PDF delegates conversion to the separate wkhtmltopdf command-line binary. As the project README explains, “The wkhtmltopdf binary is run outside of your Rails application; therefore, your normal layouts will not work.” A browser can resolve a relative URL against your Rails host, session, and asset pipeline, while the conversion process may have a different working directory, hostname, protocol, credentials, or filesystem access.
The failure is usually one of these:
- The stylesheet link in the HTML points to a relative or unavailable URL.
- A Rails 3.1 or 3.2 pipeline asset was not precompiled in production.
- The stylesheet is limited to
media="print", while wkhtmltopdf is using screen media. - An image, font, or
url(...)dependency inside the CSS cannot be loaded. - The installed Wicked PDF and wkhtmltopdf versions do not behave like the versions used by the legacy application.
Fix retrieval before changing CSS selectors. A perfect print rule cannot affect a file that the renderer never loaded.
#1 Best Overall
Identify the exact Rails 3 stack first
Record these values from the application and deployment host:
- Rails minor version: 3.0, 3.1, or 3.2.
- Whether Sprockets/the asset pipeline is enabled.
- Wicked PDF gem version and its configured executable path.
wkhtmltopdf --versionoutput.- Operating system, container or VM packaging, and the user account running the web process.
- Whether production uses asset compilation at runtime or
config.assets.compile = false.
This matters because Rails 3.0 normally serves stylesheets from public/stylesheets, while Rails 3.1 introduced Sprockets and Rails 3.2 documents app, lib, and vendor asset locations. Current Wicked PDF documentation says it is verified with Rails 4 through 7.0; that does not establish official support for every Rails 3 combination, so rely on the versions actually installed in your application.
Inspect the HTML that Wicked PDF actually converts
Do not infer the renderer’s input from an ERB template. In a controlled development or staging route, use Wicked PDF’s HTML debugging option:
show_as_html: params.key?('debug')For example, a controller action can render the PDF while allowing a debug request to display the intermediate page:
def invoice
respond_to do |format|
format.html
format.pdf do
render pdf: "invoice",
show_as_html: params.key?('debug')
end
end
endOpen the debug response and inspect the final rendered <link> element. Check the complete href, its scheme, hostname, port, and path. Copy that URL from the server environment with an HTTP client or request it from the same machine and service account that runs conversion. If the response is a redirect to login, a 404, HTML instead of CSS, or a certificate error, fix that first.
Choose the correct Rails 3 asset strategy
Rails 3.0 without Sprockets
Rails 3.0’s default stylesheet location is under public/stylesheets. Ensure the PDF stylesheet is physically present there (or in another public location your app serves) and that the generated HTML references a path the external process can reach. For non-pipeline applications, Wicked PDF recommends its helpers because they generate absolute references:
<%= wicked_pdf_stylesheet_link_tag 'pdf' %>Use the helper in the PDF layout or view rather than assuming the browser’s normal layout will be available. If your deployment serves assets from a different host, configure the URL so the generated link names that reachable host.
Rails 3.1 and 3.2 with the asset pipeline
Keep the PDF stylesheet in the pipeline’s supported location and reference it through the Rails asset helpers used by that application. In production, precompile the PDF stylesheet and every related asset. The Wicked PDF README states, “It is best to precompile assets used in PDF views.” A development request may compile an asset dynamically, while production with config.assets.compile = false will fail unless the fingerprinted files already exist.
Recommended Free Tools
After deployment, verify the compiled output and manifest rather than only checking the source file. If your stylesheet imports another stylesheet, uses images, or references fonts, those dependencies also need to be present and reachable. Restart the application or asset server after changing configuration.
Absolute URLs versus local files
An absolute HTTP(S) URL works only if the conversion host can resolve the hostname, negotiate TLS, pass any required authentication, and reach the port. A filesystem URL works only when the file exists in the renderer’s namespace and the process has permission to read it. A URL that succeeds in your laptop browser is not proof that the production web process can use it.
Make print media rules apply deliberately
Rails’ stylesheet_link_tag defaults to media="screen". Rails 3.0 documentation describes the generated default as media="screen" rel="stylesheet" type="text/css". If your PDF rules are in @media print or a link marked media="print", tell Wicked PDF to pass wkhtmltopdf’s print-media option:
render pdf: "invoice",
print_media_type: trueThat option passes --print-media-type. Confirm that the installed wkhtmltopdf build supports and honors it; binary options can vary by version. Alternatively, put the rules needed for the PDF in a stylesheet that applies under the renderer’s active media, rather than relying on print-only conditions.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsDo not use a browser’s Print Preview as a definitive match. Browser engines, wkhtmltopdf builds, font availability, JavaScript timing, and pagination can differ even when the same URL is used.
Build a minimal, testable PDF layout
Separate PDF presentation from the normal application layout so browser navigation, menus, chat controls, and responsive breakpoints do not enter the document:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<%= wicked_pdf_stylesheet_link_tag 'pdf' %>
</head>
<body>
<%= yield %>
</body>
</html>Keep the first test stylesheet simple:
body { font-family: sans-serif; color: #222; }
.invoice { width: 700px; }
@media print { .screen-only { display: none; } }Once this renders, add framework styles, images, custom fonts, and complex selectors one dependency at a time. This isolates a path problem from a cascade or pagination problem.
Check images, fonts, and CSS dependencies
A working top-level stylesheet does not prove its dependencies work. Test every src and CSS url(...) reference. Use absolute paths where necessary and confirm content types are correct. Wicked PDF documents a gotcha where one missing or incorrectly pathed image can interfere with other images in the output, so remove images temporarily when diagnosing CSS.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Use production asset URLs, not development-only ports.
- Confirm the renderer’s user can read local files.
- Make sure font files are served with a usable MIME type and do not require browser cookies.
- Check that protocol-relative URLs such as
//cdn.example.com/font.woffare replaced with explicit schemes when the renderer cannot infer one. - Prefer a PDF-specific stylesheet with predictable dimensions instead of relying on responsive viewport logic.
Production verification checklist
- Deploy the PDF stylesheet and dependencies.
- Run the asset precompile task appropriate to the Rails 3 application.
- Confirm the generated HTML contains the final absolute or readable asset references.
- Request those references from the production host, not from your workstation.
- Generate a PDF as the same operating-system user used by the application.
- Inspect application logs and wkhtmltopdf stderr for network, certificate, permission, or timeout errors.
- Compare a minimal PDF with the full template, adding dependencies until the failure reappears.
Common symptoms and fixes
All CSS is missing
The link is commonly relative, points at a development asset server, or was not precompiled. Inspect the final href, request it from the conversion host, and use the appropriate Wicked PDF helper or pipeline-generated URL.
Only print rules are missing
Enable print_media_type: true, then verify the binary honors --print-media-type. If the option is unavailable or unreliable in your build, move essential rules into the active stylesheet media.
Styles work in development but not production
Production often disables runtime compilation. Precompile the PDF stylesheet and dependencies, verify the manifest, and confirm the production hostname and protocol are reachable from the server.
Images or fonts vanish while text styling works
The CSS loaded, but a dependency did not. Check each URL, file permission, MIME type, certificate, and authentication requirement. Temporarily remove the failing resource to confirm the diagnosis.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →The debug HTML looks right but the PDF differs
The debug page is viewed by your browser, while the PDF is rendered by wkhtmltopdf. Compare the exact HTML and asset responses from the renderer’s environment, then check media selection, JavaScript timing, installed fonts, and binary version.
Changing an option has no effect
Verify the option name and the installed wkhtmltopdf version. Wicked PDF notes that binary options vary between versions. Confirm the generated command or enable the gem’s logging before assuming the setting was passed through.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Performance, reliability, and maintenance considerations
External conversion adds process startup and asset-fetch time to every request. Keep PDF stylesheets focused, avoid unnecessary remote resources, and use a background job for large or frequent documents if the application cannot tolerate request latency. Make the renderer’s binary path explicit and pin the version in deployment so an operating-system update does not silently change layout behavior.
The wkhtmltopdf GitHub repository is archived and read-only, which is a maintenance consideration for a long-lived Rails 3 system. Before migrating, compare candidate renderers on Rails/Ruby compatibility, CSS and print-layout fidelity, operating-system packaging, maintenance and security posture, ability to reuse existing views, and deployment cost. The available evidence does not justify ranking a particular replacement.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOr skip the browser setup
If you only need a clean image or PDF of a URL for a preview, test fixture, report, or monitoring workflow, ScreenshotNeo makes the capture an API request instead of a browser-and-wkhtmltopdf installation. It removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, and cache hits are not billed; and its MCP server lets Claude, Cursor, or another MCP client call take_screenshot, get_page_info, and capture_pdf.
Use the documented API details at https://screenshotneo.com/docs/. This cURL request captures Stripe as WebP:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Every response identifies the page verdict and billing status through X-Page-Verdict and X-Billed headers. Features include full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device and viewport controls, retina scale, PDF paper and margin settings, custom CSS and JavaScript, click and wait actions, request blocking, headers/cookies/user-agent/Authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification.
The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan, and yearly billing gives two months free. Start with the free ScreenshotNeo plan.
Frequently Asked Questions
Should I use media="print" or print_media_type: true?
Use print_media_type: true when the PDF depends on print-only rules, then verify your installed wkhtmltopdf build supports the option. Otherwise place required rules in the stylesheet’s active media.
Does Rails 3.0 use the same asset pipeline as Rails 3.2?
No. Rails 3.0 commonly serves files from public/stylesheets; Rails 3.1 and 3.2 use Sprockets-based asset handling when enabled. Check the application’s actual configuration before changing paths.
Why does a missing image affect unrelated PDF images?
Wicked PDF documents this as a rendering gotcha. Check every image path and remove resources individually while isolating the failing dependency.
Is Rails 3 officially supported by current Wicked PDF releases?
Current Wicked PDF documentation states verification for Rails 4 through 7.0, not Rails 3. Confirm compatibility using the versions installed in your legacy application.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
