Conversion options
Everything optional about a conversion lives on ConvertOptions. Pass null, or leave it out, for the defaults. Each conversion reads its options once, at the start, so use a fresh object per call rather than changing a shared one.
Pages, metadata and progress
This converts pages 1 and 3 of a report, stamps PDF metadata and prints each stage as it happens:
using DocWright;
using DocWright.Core.Primitives;
var options = new ConvertOptions
{
Pages = PageRange.Parse("1,3"), // print-dialog syntax: "1-3,7,12-"
Progress = new StageLogger(),
};
// Metadata is get-only: set its properties rather than replacing it.
options.Metadata.Title = "Quarterly line report";
options.Metadata.Author = "Finance";
options.Metadata.Subject = "Q3 2026";
options.Metadata.CreationDate = new DateTimeOffset(2026, 10, 1, 9, 0, 0, TimeSpan.Zero);
using (FileStream input = File.OpenRead("quarterly-report.docx"))
using (FileStream output = File.Create("pages-1-and-3.pdf"))
{
ConversionResult result = converter.Convert(input, output, options);
Console.WriteLine($"Wrote {result.PageCount} page(s).");
}
The progress reporter used above:
/// <summary>Prints each stage once. Reports arrive on the converting thread, in order.</summary>
internal sealed class StageLogger : IProgress<ConversionProgress>
{
private ConversionStage? last;
public void Report(ConversionProgress value)
{
if (value.Stage != this.last)
{
this.last = value.Stage;
string pages = value.HasPageProgress ? $" ({value.PagesCompleted}/{value.PagesTotal} pages)" : "";
Console.WriteLine($"{value.Stage}{pages}");
}
}
}
Output
Preparing
ReadingDocument
ResolvingDocument
LayingOutDocument
RenderingPages (0/2 pages)
Completed (2/2 pages)
Wrote 2 page(s).
Tip
System.Progress<T> posts each report to the thread pool, so in a console app its lines can print after the conversion returns, or out of order. Implement IProgress<ConversionProgress> yourself, as above, when order matters. In a UI app, Progress<T> is what you want: it reports on the UI thread.
Every option
| Option | Default | Meaning |
|---|---|---|
Pages |
PageRange.All |
Which pages to render. PageRange.Parse accepts print-dialog syntax: "1-3,7,12-". |
SourceFormat |
Auto |
What the input is. Required for plain text, which is never detected, and advisable for Markdown. |
Metadata |
empty | PDF Title, Author, Subject, Keywords, Creator, Producer, CreationDate and Conformance (PDF/A). Get-only: set its properties. |
Limits |
safe defaults | Caps on size, time, pages, memory and nesting. See Hardening untrusted input. |
Diagnostics |
null |
Where warnings about degraded content go. See Diagnostics and strict mode. |
Progress |
null |
Stage and page-count callbacks. |
StrictMode |
false |
Throw UnsupportedFeatureException instead of rendering a degraded result. |
Password |
null |
Opens an encrypted document or PDF. See Encryption. |
TaggedPdf |
false |
Write a structure tree for assistive technology. See PDF/A and tagged PDF. |
DefaultLanguage |
null |
The PDF language when the document declares none, for example "en-GB". |
FontDirectories, FontFallbackChain, ScriptFallbackFonts |
empty | Font sources and substitutes. See Fonts and complex scripts. |
IncludeSystemFontDirectories, IncludeBundledMetricFonts |
true |
Whether the operating-system fonts and the bundled substitutes are used. See The same output on every machine. |
WarnOnFontSubstitution, FailOnFontSubstitution |
false |
Report, or refuse, font substitutions. |
TextShaper |
null |
A text shaper for complex scripts, such as HarfBuzzTextShaper. |
RenderRevisions |
false |
Reserved: drawing revision marks is not implemented yet. Revisions are always applied. |
Deterministic by default
DocWright writes no timestamp unless you set Metadata.CreationDate. The same input and options therefore give byte-identical output on every machine, which makes PDFs easy to cache, hash and test. Set the date when you want it recorded.
Telling DocWright what the input is
Convert, ConvertAsync and ConvertToImages detect DOCX, DOC, RTF and HTML from their content. Markdown has only a weak signature and plain text has none, so name them:
using DocWright;
using DocWright.Core.Primitives;
// Markdown's signature is weak and plain text has none: say what the input is.
using (FileStream input = File.OpenRead("article.md"))
using (FileStream output = File.Create("article.pdf"))
{
converter.Convert(input, output, new ConvertOptions { SourceFormat = FormatDetection.Markdown });
}

Load takes the format as its second argument instead: converter.Load(stream, FormatDetection.Text).
Things that follow the document, not an option
- Hidden text is never rendered. Text marked hidden in Word takes no space and is left out of the PDF entirely, including the PDF's extractable text, so hidden notes and prices can't leak.
GetText()and the text exports still include it, because it is still in the document. - East Asian line breaking follows the document's compatibility mode, as it does in Word. To get Word 2013's rules for an older document, set
document.Settings.CompatibilityMode = 15before converting. - Some older documents fit lines differently. Below compatibility mode 15,
w:eastAsiaTheme="minorEastAsia"ormajorEastAsiainw:docDefaultsmakes lines share their slack by each space's room, as Word does. Word's RTF import writes it; its template for Western text writesminorHAnsi, which doesn't count. Ifdocument.Settings.CharacterSpacingControlalso compresses punctuation, a line may shrink its spaces to keep the first word that overflows, so line breaks can differ.UseWord97LineBreakRulesandBalanceSingleByteDoubleByteWidthtogether turn that off, and an RTF document has both on. - Word 2010-format documents kern as Word does. Below mode 15 the compat setting
enableOpenTypeFeatures, which Word writes itself, selects the font's GPOS kerning, so their line breaks can change from earlier releases. - A fixed-layout table keeps its declared widths, even past the page's edge, and a cell's width beats the grid. A table nested in a cell still shrinks to it.
- Ligatures are drawn as Word draws them. Word's template asks for them, so
officeuses the font's ownffiglyph where it has one, in compatibility mode 15 or underenableOpenTypeFeatures, and not on a run with character spacing. Extracted text still readsoffice. Aptos's ligatures are as wide as their letters, but Calibri's and Candara's are narrower, so line breaks and page counts can change for documents in those fonts.