https://github.com/portabletext/dotnet-portable-text
Library for working with Portable Text in C#.
https://github.com/portabletext/dotnet-portable-text
portable-text
Last synced: over 1 year ago
JSON representation
Library for working with Portable Text in C#.
- Host: GitHub
- URL: https://github.com/portabletext/dotnet-portable-text
- Owner: portabletext
- License: mit
- Created: 2020-06-07T11:20:27.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2025-02-11T10:05:55.000Z (over 1 year ago)
- Last Synced: 2025-03-23T12:04:21.134Z (over 1 year ago)
- Topics: portable-text
- Language: C#
- Homepage:
- Size: 1.01 MB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/saasen/dotnet-portable-text/actions/workflows/test.yml)
# .NET Portable Text
This repo contains tools for working with [Portable Text](https://portabletext.org) in .NET.
## Installation
```
dotnet add package PortableText
```
## Basic Usage
### Rendering
```cs
using PortableText;
var result = PortableTextToHtml.Render(
json, // A string value representing your Portable Text
serializers // Optional. Specifies how to render a certain type, mark, list etc.
);
```
## Customizing rendering
You can pass custom serializers in the `serializers` parameter.
### Types
A type serializer takes in a JSON de-serialized type representing your data.
This example shows how to render a custom type:
```cs
var serializers = new PortableTextSerializers
{
TypeSerializers = new Dictionary
{
{
"youtubeEmbed", new TypeSerializer
{
Type = typeof(YoutubeEmbed),
Serialize = (value, rawValue, serializers, isInline) =>
{
// We are specifying which type we want the JSON de-serialized to, so this is safe.
var typedBlock = value as YoutubeEmbed;
return $@"";
}
}
}
}
};
var result = PortableTextToHtml.Render(
json,
serializers
);
```
### Block styles
Block styles typically describes a visual property for the whole block.
You can customize rendering of block styles like this:
```cs
var serializers = new PortableTextSerializers
{
BlockStyleSerializers = new Dictionary, string>>
{
{ "h1", blocks => @$"
{string.Join(string.Empty, blocks)}
" }
}
};
var result = PortableTextToHtml.Render(
json,
serializers
);
```
### Marks
This library separates annotation marks and decorator marks.
#### Decorator marks
Decorator marks are marks that mean something by themselves.
Examples of decorator marks would be "em" or "strong" which could mean to emphasize or bold text.
This example shows how to render a in-line link in your text:
```cs
var serializers = new PortableTextSerializers
{
MarkSerializers =
{
Decorators = new Dictionary>
{
{
"highlight", () => ("", ">")
}
}
}
};
var result = PortableTextToHtml.Render(
json,
serializers
);
```
#### Annotation marks
Annotation marks are marks that needs additional information other than the name of the mark itself for it to be useful.
Examples of this would be a "link". A link needs a URL to be meaningful.
```cs
public class LinkPortableTextMarkAnnotation
{
public string Href { get; set; }
}
var serializers = new PortableTextSerializers
{
MarkSerializers =
{
Annotations = new Dictionary
{
{
"link",
new AnnotatedMarkSerializer
{
Type = typeof(LinkPortableTextMarkAnnotation),
Serialize = (value, rawValue) =>
{
var typed = value as LinkPortableTextMarkAnnotation;
return ($@"", "");
}
}
}
}
}
};
var result = PortableTextToHtml.Render(
json,
serializers
);
```
### Lists
This example shows how to customize rendering of a list. It uses the thumbs up sign as the list style type:
```cs
var serializers = new PortableTextSerializers
{
ListSerializers = new Dictionary, string>>()
{
{ "bullet", listItems => @$"
- {string.Join(string.Empty, listItems)}
}
};
var result = PortableTextToHtml.Render(
json,
serializers
);
```
### List items
This example shows how to customize rendering of a list item:
```cs
var serializers = new PortableTextSerializers
{
ListItemSerializers = new Dictionary>
{
{ "bullet", () => (@"
}
};
var result = PortableTextToHtml.Render(
json,
serializers
);
```
## Unknown types
When this library encounters unknown types, they are ignored and you get no warnings.
If your type isn't outputted, you are probably missing a serializer for it.
## License
MIT © [Anders Stensaas](https://github.com/saasen/)