Ruby Portable Text

A ruby library to render Portable text

This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.

You can:

easily render default PortableText blocks in html without any configuration
create custom block types, mark_defs. Add them or replace existing ones.
create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
customize each HTML node with custom attributes
create a new serializer

This is a very early release so please open issues if something doesn't work as intended.

Installation

gem install portable_text

Usage

See Rails usage for usage in rails

PortableText::Serializer takes 2 parameters:

content: , the portable text Array
to: , the rendering format. It defaults to: :html

You can also use the :plain rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.

PortableText accepts 2 methods, render and convert!.

render renders the content to the specified format defined in the to parameter. See How to render html ? for more information.
convert! converts the content to be used by the library.
- It is useful for debugging purposes.
- It transforms the keys to ruby format.
- It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.

How to render html?

Under the hood, the html renderer uses Phlex, a templating language which allows to create html in plain ruby.

content=[{"_key": "12345ffxx","_type": "block","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Hello world!"}],"markDefs": [],"style": "h1"}]portable_text=PortableText::Serializer.new(content: content,to: :html)# Since the HTML renderer uses Phlex, you can either include the rendering module # and use the render method...includePortableText::Html::Renderingrenderportable_text.render# => <h1>Hello world!</h1># ... Or you can directly call the Phlex templateportable_text.render.call# => <h1>Hello world!</h1>

Rails usage

To use the PortableText HTML serializer in rails, you need to add phlex-rails to the Gemfile.

You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.

gem'portable_text'gem'phlex-rails'

Then run bundle install

Then, in a controller or a view, just use render as usual.

portable_text=PortableText::Serializer.new(content: content,to: :html)renderportable_text.render

Configuration

This library is highly customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.

Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.

So, in order to use a block type or a mark definition, one has to:

register it in the PortableText configuration, so it can be passed as an object to the serializer
create the template in the serializer (see HTML configuration)

Registering block types

content=[{"_key": "12345ffxx","_type": "myType", ...,"url": "https://www.github.com","image_url": "https://www.myimage.com/my_image.jpg","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Github"}]}]# Under the hood, this library uses dry-initializer.# You can use the option method to configure it easilyclassMyBlock < PortableText::BlockTypes::Baseoption:url,default: proc{""}option:image_url,default: proc{""}# children is an inherited option so it does not need to be added hereend# Or use plain old ruby. It needs to have attr_readers!classMyBlock < PortableText::BlockTypes::Baseattr_reader:url,:image_urldefinitialize(url: "",image_url:, **)super@url=url@image_url=image_urlendend# PortableText transforms keys to ruby format so use conventional ruby!# myType becomes my_type.PortableText.config.block.types.merge!{my_block: MyBlock}

Default block types

It’s probably a good idea to leave the list block type untouched. Change at your own risk.

{block: BlockTypes::Block,image: BlockTypes::Image,list: BlockTypes::List,span: BlockTypes::Span}

Registering mark definitions

It’s very similar to registering blocks. In case of doubt, refer to the block documentation.

content=[{"_key": "12345ffxx","_type": "block", ...,"markDefs": [{"_key"=>"456","_type"=>"newMarkDef"}],}]classNewMarkDef < PortableText::MarkDefs::Baseoption:label,default: proc{""}endPortableText.config.block.mark_defs.merge!{new_mark_def: NewMarkDef}

Html Serializer configuration

After registering your block type or mark definition, you need to create its template.

Each template takes one argument, a block.

Block Type Template

# Let's use the block defined earlier in Registering block typesclassHtml::MyBlock < PortableText::Html::BaseComponent# You can include PortableText::Html::Configured # to get access to the html serializer configuration helpers# The #config method allows you to access config values # The #block_type(:key) method is a shortcut to the relevant block_typeincludePortableText::Html::Configured# This library uses dry-initializer # so you can use `param` to create a simple parameter# There is no attribute_reader so `param :my_block` generates `@my_block`# This is recommended because some common HTML method names could conflict with# Phlex methods, like `title`. param:my_blockdefview_templatedivdoimg(src: @my_block.image_url)linkendendprivatedeflinka(href: @my_block.url)do@my_block.children.eachdo |child|
renderblock_type(:span).new(child,mark_defs: nil)endendendend# It needs to have the same key as the one registered before.PortableText::Html.config.block.types.merge!{my_block: Html::MyBlock}

Mark Definition template

Each mark definition takes one argument, a mark definition registered in the configuration.

# Let's use the mark definition defined earlier in Registering mark definitionclassHtml::NewMarkDef < PortableText::Html::BaseComponentparam:mark_def# &block is mandatory because mark definitions always contain other nodesdefview_template(&block)a(href: @mark_def.url){block.call}endend# It needs to have the same key as the one registered before.PortableText::Html.config.block.mark_defs.merge!{new_mark_def: Html::NewMarkDef}

Customizing html nodes

Every HTML node is customizable through config and looks this way:

h1: { node: :h1 }

You can add HTML attributes by appending them. For example:

h1: {node: :h1,class:"header"}

Configuring marks

You can configure marks by updating the marks setting.

PortableText::Html.config.span.marks.merge!{strong: {node: :b,}}# Defaults{strong: {node: :strong},em: {node: :em}}

Configuring styles

PortableText::Html.config.block.styles.merge!{h1: {node: :h3,class: "header"}}# Defaults{h1: {node: :h1},h2: {node: :h2},h3: {node: :h3},h4: {node: :h4},h5: {node: :h5},h6: {node: :h6},blockquote: {node: :blockquote},normal: {node: :p},li: {node: :li}}

Configuring list types

PortableText::Html.config.block.list_types.merge!{bullet: {node: :div}}# Defaults{bullet: {node: :ul},numeric: {node: :ol}}

Adding a new serializer

You can add a new serializer by creating a new class. You then need to add it the the config.

The serializer needs to have a content method and takes a list of blocks as only parameter.

classMySerializerdefinitialize(blocks)@blocks=blocksenddefcontent(**options)blocks.map |block|
block.type + " - " + block.key + " - " + options[:context]end.join(" ")endendPortableText.config.serializers.merge!{my_serializer: MySerializer}content=[{"_key": "12345ffxx","_type": "block", ... }]serializer=PortableText::Serializer.new(content: content,to: :my_serializer)# render forwards any keyword argument to the content method in the serializerserializer.render(context: "readme")# => block - 12345ffxx - readme

Acknowledgments

Thanks to Joel Drapper and Will Cosgrove for their help in building the HTML serializer!

Ruby Portable Text

A ruby library to render Portable text

This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.

You can:

easily render default PortableText blocks in html without any configuration
create custom block types, mark_defs. Add them or replace existing ones.
create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
customize each HTML node with custom attributes
create a new serializer

This is a very early release so please open issues if something doesn't work as intended.

Installation

gem install portable_text

Usage

See Rails usage for usage in rails

PortableText::Serializer takes 2 parameters:

content: , the portable text Array
to: , the rendering format. It defaults to: :html

You can also use the :plain rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.

PortableText accepts 2 methods, render and convert!.

render renders the content to the specified format defined in the to parameter. See How to render html ? for more information.
convert! converts the content to be used by the library.
- It is useful for debugging purposes.
- It transforms the keys to ruby format.
- It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.

How to render html?

Under the hood, the html renderer uses Phlex, a templating language which allows to create html in plain ruby.

content=[{"_key": "12345ffxx","_type": "block","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Hello world!"}],"markDefs": [],"style": "h1"}]portable_text=PortableText::Serializer.new(content: content,to: :html)# Since the HTML renderer uses Phlex, you can either include the rendering module # and use the render method...includePortableText::Html::Renderingrenderportable_text.render# => <h1>Hello world!</h1># ... Or you can directly call the Phlex templateportable_text.render.call# => <h1>Hello world!</h1>

Rails usage

To use the PortableText HTML serializer in rails, you need to add phlex-rails to the Gemfile.

You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.

gem'portable_text'gem'phlex-rails'

Then run bundle install

Then, in a controller or a view, just use render as usual.

portable_text=PortableText::Serializer.new(content: content,to: :html)renderportable_text.render

Configuration

This library is highly customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.

Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.

So, in order to use a block type or a mark definition, one has to:

register it in the PortableText configuration, so it can be passed as an object to the serializer
create the template in the serializer (see HTML configuration)

Registering block types

content=[{"_key": "12345ffxx","_type": "myType", ...,"url": "https://www.github.com","image_url": "https://www.myimage.com/my_image.jpg","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Github"}]}]# Under the hood, this library uses dry-initializer.# You can use the option method to configure it easilyclassMyBlock < PortableText::BlockTypes::Baseoption:url,default: proc{""}option:image_url,default: proc{""}# children is an inherited option so it does not need to be added hereend# Or use plain old ruby. It needs to have attr_readers!classMyBlock < PortableText::BlockTypes::Baseattr_reader:url,:image_urldefinitialize(url: "",image_url:, **)super@url=url@image_url=image_urlendend# PortableText transforms keys to ruby format so use conventional ruby!# myType becomes my_type.PortableText.config.block.types.merge!{my_block: MyBlock}

Default block types

It’s probably a good idea to leave the list block type untouched. Change at your own risk.

{block: BlockTypes::Block,image: BlockTypes::Image,list: BlockTypes::List,span: BlockTypes::Span}

Registering mark definitions

It’s very similar to registering blocks. In case of doubt, refer to the block documentation.

content=[{"_key": "12345ffxx","_type": "block", ...,"markDefs": [{"_key"=>"456","_type"=>"newMarkDef"}],}]classNewMarkDef < PortableText::MarkDefs::Baseoption:label,default: proc{""}endPortableText.config.block.mark_defs.merge!{new_mark_def: NewMarkDef}

Html Serializer configuration

After registering your block type or mark definition, you need to create its template.

Each template takes one argument, a block.

Block Type Template

# Let's use the block defined earlier in Registering block typesclassHtml::MyBlock < PortableText::Html::BaseComponent# You can include PortableText::Html::Configured # to get access to the html serializer configuration helpers# The #config method allows you to access config values # The #block_type(:key) method is a shortcut to the relevant block_typeincludePortableText::Html::Configured# This library uses dry-initializer # so you can use `param` to create a simple parameter# There is no attribute_reader so `param :my_block` generates `@my_block`# This is recommended because some common HTML method names could conflict with# Phlex methods, like `title`. param:my_blockdefview_templatedivdoimg(src: @my_block.image_url)linkendendprivatedeflinka(href: @my_block.url)do@my_block.children.eachdo |child|
renderblock_type(:span).new(child,mark_defs: nil)endendendend# It needs to have the same key as the one registered before.PortableText::Html.config.block.types.merge!{my_block: Html::MyBlock}

Mark Definition template

Each mark definition takes one argument, a mark definition registered in the configuration.

# Let's use the mark definition defined earlier in Registering mark definitionclassHtml::NewMarkDef < PortableText::Html::BaseComponentparam:mark_def# &block is mandatory because mark definitions always contain other nodesdefview_template(&block)a(href: @mark_def.url){block.call}endend# It needs to have the same key as the one registered before.PortableText::Html.config.block.mark_defs.merge!{new_mark_def: Html::NewMarkDef}

Customizing html nodes

Every HTML node is customizable through config and looks this way:

h1: { node: :h1 }

You can add HTML attributes by appending them. For example:

h1: {node: :h1,class:"header"}

Configuring marks

You can configure marks by updating the marks setting.

PortableText::Html.config.span.marks.merge!{strong: {node: :b,}}# Defaults{strong: {node: :strong},em: {node: :em}}

Configuring styles

PortableText::Html.config.block.styles.merge!{h1: {node: :h3,class: "header"}}# Defaults{h1: {node: :h1},h2: {node: :h2},h3: {node: :h3},h4: {node: :h4},h5: {node: :h5},h6: {node: :h6},blockquote: {node: :blockquote},normal: {node: :p},li: {node: :li}}

Configuring list types

PortableText::Html.config.block.list_types.merge!{bullet: {node: :div}}# Defaults{bullet: {node: :ul},numeric: {node: :ol}}

Adding a new serializer

You can add a new serializer by creating a new class. You then need to add it the the config.

The serializer needs to have a content method and takes a list of blocks as only parameter.

classMySerializerdefinitialize(blocks)@blocks=blocksenddefcontent(**options)blocks.map |block|
block.type + " - " + block.key + " - " + options[:context]end.join(" ")endendPortableText.config.serializers.merge!{my_serializer: MySerializer}content=[{"_key": "12345ffxx","_type": "block", ... }]serializer=PortableText::Serializer.new(content: content,to: :my_serializer)# render forwards any keyword argument to the content method in the serializerserializer.render(context: "readme")# => block - 12345ffxx - readme

Acknowledgments

Thanks to Joel Drapper and Will Cosgrove for their help in building the HTML serializer!

Ruby Portable Text

A ruby library to render Portable text

This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.

You can:

easily render default PortableText blocks in html without any configuration
create custom block types, mark_defs. Add them or replace existing ones.
create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
customize each HTML node with custom attributes
create a new serializer

This is a very early release so please open issues if something doesn't work as intended.

Installation

gem install portable_text

Usage

See Rails usage for usage in rails

PortableText::Serializer takes 2 parameters:

content: , the portable text Array
to: , the rendering format. It defaults to: :html

You can also use the :plain rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.

PortableText accepts 2 methods, render and convert!.

render renders the content to the specified format defined in the to parameter. See How to render html ? for more information.
convert! converts the content to be used by the library.
- It is useful for debugging purposes.
- It transforms the keys to ruby format.
- It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.

How to render html?

Under the hood, the html renderer uses Phlex, a templating language which allows to create html in plain ruby.

content=[{"_key": "12345ffxx","_type": "block","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Hello world!"}],"markDefs": [],"style": "h1"}]portable_text=PortableText::Serializer.new(content: content,to: :html)# Since the HTML renderer uses Phlex, you can either include the rendering module # and use the render method...includePortableText::Html::Renderingrenderportable_text.render# => <h1>Hello world!</h1># ... Or you can directly call the Phlex templateportable_text.render.call# => <h1>Hello world!</h1>

Rails usage

To use the PortableText HTML serializer in rails, you need to add phlex-rails to the Gemfile.

You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.

gem'portable_text'gem'phlex-rails'

Then run bundle install

Then, in a controller or a view, just use render as usual.

portable_text=PortableText::Serializer.new(content: content,to: :html)renderportable_text.render

Configuration

This library is highly customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.

Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.

So, in order to use a block type or a mark definition, one has to:

register it in the PortableText configuration, so it can be passed as an object to the serializer
create the template in the serializer (see HTML configuration)

Registering block types

content=[{"_key": "12345ffxx","_type": "myType", ...,"url": "https://www.github.com","image_url": "https://www.myimage.com/my_image.jpg","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Github"}]}]# Under the hood, this library uses dry-initializer.# You can use the option method to configure it easilyclassMyBlock < PortableText::BlockTypes::Baseoption:url,default: proc{""}option:image_url,default: proc{""}# children is an inherited option so it does not need to be added hereend# Or use plain old ruby. It needs to have attr_readers!classMyBlock < PortableText::BlockTypes::Baseattr_reader:url,:image_urldefinitialize(url: "",image_url:, **)super@url=url@image_url=image_urlendend# PortableText transforms keys to ruby format so use conventional ruby!# myType becomes my_type.PortableText.config.block.types.merge!{my_block: MyBlock}

Default block types

It’s probably a good idea to leave the list block type untouched. Change at your own risk.

{block: BlockTypes::Block,image: BlockTypes::Image,list: BlockTypes::List,span: BlockTypes::Span}

Registering mark definitions

It’s very similar to registering blocks. In case of doubt, refer to the block documentation.

content=[{"_key": "12345ffxx","_type": "block", ...,"markDefs": [{"_key"=>"456","_type"=>"newMarkDef"}],}]classNewMarkDef < PortableText::MarkDefs::Baseoption:label,default: proc{""}endPortableText.config.block.mark_defs.merge!{new_mark_def: NewMarkDef}

Html Serializer configuration

After registering your block type or mark definition, you need to create its template.

Each template takes one argument, a block.

Block Type Template

# Let's use the block defined earlier in Registering block typesclassHtml::MyBlock < PortableText::Html::BaseComponent# You can include PortableText::Html::Configured # to get access to the html serializer configuration helpers# The #config method allows you to access config values # The #block_type(:key) method is a shortcut to the relevant block_typeincludePortableText::Html::Configured# This library uses dry-initializer # so you can use `param` to create a simple parameter# There is no attribute_reader so `param :my_block` generates `@my_block`# This is recommended because some common HTML method names could conflict with# Phlex methods, like `title`. param:my_blockdefview_templatedivdoimg(src: @my_block.image_url)linkendendprivatedeflinka(href: @my_block.url)do@my_block.children.eachdo |child|
renderblock_type(:span).new(child,mark_defs: nil)endendendend# It needs to have the same key as the one registered before.PortableText::Html.config.block.types.merge!{my_block: Html::MyBlock}

Mark Definition template

Each mark definition takes one argument, a mark definition registered in the configuration.

# Let's use the mark definition defined earlier in Registering mark definitionclassHtml::NewMarkDef < PortableText::Html::BaseComponentparam:mark_def# &block is mandatory because mark definitions always contain other nodesdefview_template(&block)a(href: @mark_def.url){block.call}endend# It needs to have the same key as the one registered before.PortableText::Html.config.block.mark_defs.merge!{new_mark_def: Html::NewMarkDef}

Customizing html nodes

Every HTML node is customizable through config and looks this way:

h1: { node: :h1 }

You can add HTML attributes by appending them. For example:

h1: {node: :h1,class:"header"}

Configuring marks

You can configure marks by updating the marks setting.

PortableText::Html.config.span.marks.merge!{strong: {node: :b,}}# Defaults{strong: {node: :strong},em: {node: :em}}

Configuring styles

PortableText::Html.config.block.styles.merge!{h1: {node: :h3,class: "header"}}# Defaults{h1: {node: :h1},h2: {node: :h2},h3: {node: :h3},h4: {node: :h4},h5: {node: :h5},h6: {node: :h6},blockquote: {node: :blockquote},normal: {node: :p},li: {node: :li}}

Configuring list types

PortableText::Html.config.block.list_types.merge!{bullet: {node: :div}}# Defaults{bullet: {node: :ul},numeric: {node: :ol}}

Adding a new serializer

You can add a new serializer by creating a new class. You then need to add it the the config.

The serializer needs to have a content method and takes a list of blocks as only parameter.

classMySerializerdefinitialize(blocks)@blocks=blocksenddefcontent(**options)blocks.map |block|
block.type + " - " + block.key + " - " + options[:context]end.join(" ")endendPortableText.config.serializers.merge!{my_serializer: MySerializer}content=[{"_key": "12345ffxx","_type": "block", ... }]serializer=PortableText::Serializer.new(content: content,to: :my_serializer)# render forwards any keyword argument to the content method in the serializerserializer.render(context: "readme")# => block - 12345ffxx - readme

Acknowledgments

Thanks to Joel Drapper and Will Cosgrove for their help in building the HTML serializer!

Ruby Portable Text

A ruby library to render Portable text

This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.

You can:

easily render default PortableText blocks in html without any configuration
create custom block types, mark_defs. Add them or replace existing ones.
create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
customize each HTML node with custom attributes
create a new serializer

This is a very early release so please open issues if something doesn't work as intended.

Installation

gem install portable_text

Usage

See Rails usage for usage in rails

PortableText::Serializer takes 2 parameters:

content: , the portable text Array
to: , the rendering format. It defaults to: :html

You can also use the :plain rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.

PortableText accepts 2 methods, render and convert!.

render renders the content to the specified format defined in the to parameter. See How to render html ? for more information.
convert! converts the content to be used by the library.
- It is useful for debugging purposes.
- It transforms the keys to ruby format.
- It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.

How to render html?

Under the hood, the html renderer uses Phlex, a templating language which allows to create html in plain ruby.

content=[{"_key": "12345ffxx","_type": "block","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Hello world!"}],"markDefs": [],"style": "h1"}]portable_text=PortableText::Serializer.new(content: content,to: :html)# Since the HTML renderer uses Phlex, you can either include the rendering module # and use the render method...includePortableText::Html::Renderingrenderportable_text.render# => <h1>Hello world!</h1># ... Or you can directly call the Phlex templateportable_text.render.call# => <h1>Hello world!</h1>

Rails usage

To use the PortableText HTML serializer in rails, you need to add phlex-rails to the Gemfile.

You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.

gem'portable_text'gem'phlex-rails'

Then run bundle install

Then, in a controller or a view, just use render as usual.

portable_text=PortableText::Serializer.new(content: content,to: :html)renderportable_text.render

Configuration

This library is highly customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.

Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.

So, in order to use a block type or a mark definition, one has to:

register it in the PortableText configuration, so it can be passed as an object to the serializer
create the template in the serializer (see HTML configuration)

Registering block types

content=[{"_key": "12345ffxx","_type": "myType", ...,"url": "https://www.github.com","image_url": "https://www.myimage.com/my_image.jpg","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Github"}]}]# Under the hood, this library uses dry-initializer.# You can use the option method to configure it easilyclassMyBlock < PortableText::BlockTypes::Baseoption:url,default: proc{""}option:image_url,default: proc{""}# children is an inherited option so it does not need to be added hereend# Or use plain old ruby. It needs to have attr_readers!classMyBlock < PortableText::BlockTypes::Baseattr_reader:url,:image_urldefinitialize(url: "",image_url:, **)super@url=url@image_url=image_urlendend# PortableText transforms keys to ruby format so use conventional ruby!# myType becomes my_type.PortableText.config.block.types.merge!{my_block: MyBlock}

Default block types

It’s probably a good idea to leave the list block type untouched. Change at your own risk.

{block: BlockTypes::Block,image: BlockTypes::Image,list: BlockTypes::List,span: BlockTypes::Span}

Registering mark definitions

It’s very similar to registering blocks. In case of doubt, refer to the block documentation.

content=[{"_key": "12345ffxx","_type": "block", ...,"markDefs": [{"_key"=>"456","_type"=>"newMarkDef"}],}]classNewMarkDef < PortableText::MarkDefs::Baseoption:label,default: proc{""}endPortableText.config.block.mark_defs.merge!{new_mark_def: NewMarkDef}

Html Serializer configuration

After registering your block type or mark definition, you need to create its template.

Each template takes one argument, a block.

Block Type Template

# Let's use the block defined earlier in Registering block typesclassHtml::MyBlock < PortableText::Html::BaseComponent# You can include PortableText::Html::Configured # to get access to the html serializer configuration helpers# The #config method allows you to access config values # The #block_type(:key) method is a shortcut to the relevant block_typeincludePortableText::Html::Configured# This library uses dry-initializer # so you can use `param` to create a simple parameter# There is no attribute_reader so `param :my_block` generates `@my_block`# This is recommended because some common HTML method names could conflict with# Phlex methods, like `title`. param:my_blockdefview_templatedivdoimg(src: @my_block.image_url)linkendendprivatedeflinka(href: @my_block.url)do@my_block.children.eachdo |child|
renderblock_type(:span).new(child,mark_defs: nil)endendendend# It needs to have the same key as the one registered before.PortableText::Html.config.block.types.merge!{my_block: Html::MyBlock}

Mark Definition template

Each mark definition takes one argument, a mark definition registered in the configuration.

# Let's use the mark definition defined earlier in Registering mark definitionclassHtml::NewMarkDef < PortableText::Html::BaseComponentparam:mark_def# &block is mandatory because mark definitions always contain other nodesdefview_template(&block)a(href: @mark_def.url){block.call}endend# It needs to have the same key as the one registered before.PortableText::Html.config.block.mark_defs.merge!{new_mark_def: Html::NewMarkDef}

Customizing html nodes

Every HTML node is customizable through config and looks this way:

h1: { node: :h1 }

You can add HTML attributes by appending them. For example:

h1: {node: :h1,class:"header"}

Configuring marks

You can configure marks by updating the marks setting.

PortableText::Html.config.span.marks.merge!{strong: {node: :b,}}# Defaults{strong: {node: :strong},em: {node: :em}}

Configuring styles

PortableText::Html.config.block.styles.merge!{h1: {node: :h3,class: "header"}}# Defaults{h1: {node: :h1},h2: {node: :h2},h3: {node: :h3},h4: {node: :h4},h5: {node: :h5},h6: {node: :h6},blockquote: {node: :blockquote},normal: {node: :p},li: {node: :li}}

Configuring list types

PortableText::Html.config.block.list_types.merge!{bullet: {node: :div}}# Defaults{bullet: {node: :ul},numeric: {node: :ol}}

Adding a new serializer

You can add a new serializer by creating a new class. You then need to add it the the config.

The serializer needs to have a content method and takes a list of blocks as only parameter.

classMySerializerdefinitialize(blocks)@blocks=blocksenddefcontent(**options)blocks.map |block|
block.type + " - " + block.key + " - " + options[:context]end.join(" ")endendPortableText.config.serializers.merge!{my_serializer: MySerializer}content=[{"_key": "12345ffxx","_type": "block", ... }]serializer=PortableText::Serializer.new(content: content,to: :my_serializer)# render forwards any keyword argument to the content method in the serializerserializer.render(context: "readme")# => block - 12345ffxx - readme

Acknowledgments

Thanks to Joel Drapper and Will Cosgrove for their help in building the HTML serializer!

Ruby Portable Text

A ruby library to render Portable text

This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.

You can:

easily render default PortableText blocks in html without any configuration
create custom block types, mark_defs. Add them or replace existing ones.
create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
customize each HTML node with custom attributes
create a new serializer

This is a very early release so please open issues if something doesn't work as intended.

Installation

gem install portable_text

Usage

See Rails usage for usage in rails

PortableText::Serializer takes 2 parameters:

content: , the portable text Array
to: , the rendering format. It defaults to: :html

You can also use the :plain rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.

PortableText accepts 2 methods, render and convert!.

render renders the content to the specified format defined in the to parameter. See How to render html ? for more information.
convert! converts the content to be used by the library.
- It is useful for debugging purposes.
- It transforms the keys to ruby format.
- It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.

How to render html?

Under the hood, the html renderer uses Phlex, a templating language which allows to create html in plain ruby.

content=[{"_key": "12345ffxx","_type": "block","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Hello world!"}],"markDefs": [],"style": "h1"}]portable_text=PortableText::Serializer.new(content: content,to: :html)# Since the HTML renderer uses Phlex, you can either include the rendering module # and use the render method...includePortableText::Html::Renderingrenderportable_text.render# => <h1>Hello world!</h1># ... Or you can directly call the Phlex templateportable_text.render.call# => <h1>Hello world!</h1>

Rails usage

To use the PortableText HTML serializer in rails, you need to add phlex-rails to the Gemfile.

You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.

gem'portable_text'gem'phlex-rails'

Then run bundle install

Then, in a controller or a view, just use render as usual.

portable_text=PortableText::Serializer.new(content: content,to: :html)renderportable_text.render

Configuration

This library is highly customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.

Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.

So, in order to use a block type or a mark definition, one has to:

register it in the PortableText configuration, so it can be passed as an object to the serializer
create the template in the serializer (see HTML configuration)

Registering block types

content=[{"_key": "12345ffxx","_type": "myType", ...,"url": "https://www.github.com","image_url": "https://www.myimage.com/my_image.jpg","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Github"}]}]# Under the hood, this library uses dry-initializer.# You can use the option method to configure it easilyclassMyBlock < PortableText::BlockTypes::Baseoption:url,default: proc{""}option:image_url,default: proc{""}# children is an inherited option so it does not need to be added hereend# Or use plain old ruby. It needs to have attr_readers!classMyBlock < PortableText::BlockTypes::Baseattr_reader:url,:image_urldefinitialize(url: "",image_url:, **)super@url=url@image_url=image_urlendend# PortableText transforms keys to ruby format so use conventional ruby!# myType becomes my_type.PortableText.config.block.types.merge!{my_block: MyBlock}

Default block types

It’s probably a good idea to leave the list block type untouched. Change at your own risk.

{block: BlockTypes::Block,image: BlockTypes::Image,list: BlockTypes::List,span: BlockTypes::Span}

Registering mark definitions

It’s very similar to registering blocks. In case of doubt, refer to the block documentation.

content=[{"_key": "12345ffxx","_type": "block", ...,"markDefs": [{"_key"=>"456","_type"=>"newMarkDef"}],}]classNewMarkDef < PortableText::MarkDefs::Baseoption:label,default: proc{""}endPortableText.config.block.mark_defs.merge!{new_mark_def: NewMarkDef}

Html Serializer configuration

After registering your block type or mark definition, you need to create its template.

Each template takes one argument, a block.

Block Type Template

# Let's use the block defined earlier in Registering block typesclassHtml::MyBlock < PortableText::Html::BaseComponent# You can include PortableText::Html::Configured # to get access to the html serializer configuration helpers# The #config method allows you to access config values # The #block_type(:key) method is a shortcut to the relevant block_typeincludePortableText::Html::Configured# This library uses dry-initializer # so you can use `param` to create a simple parameter# There is no attribute_reader so `param :my_block` generates `@my_block`# This is recommended because some common HTML method names could conflict with# Phlex methods, like `title`. param:my_blockdefview_templatedivdoimg(src: @my_block.image_url)linkendendprivatedeflinka(href: @my_block.url)do@my_block.children.eachdo |child|
renderblock_type(:span).new(child,mark_defs: nil)endendendend# It needs to have the same key as the one registered before.PortableText::Html.config.block.types.merge!{my_block: Html::MyBlock}

Mark Definition template

Each mark definition takes one argument, a mark definition registered in the configuration.

# Let's use the mark definition defined earlier in Registering mark definitionclassHtml::NewMarkDef < PortableText::Html::BaseComponentparam:mark_def# &block is mandatory because mark definitions always contain other nodesdefview_template(&block)a(href: @mark_def.url){block.call}endend# It needs to have the same key as the one registered before.PortableText::Html.config.block.mark_defs.merge!{new_mark_def: Html::NewMarkDef}

Customizing html nodes

Every HTML node is customizable through config and looks this way:

h1: { node: :h1 }

You can add HTML attributes by appending them. For example:

h1: {node: :h1,class:"header"}

Configuring marks

You can configure marks by updating the marks setting.

PortableText::Html.config.span.marks.merge!{strong: {node: :b,}}# Defaults{strong: {node: :strong},em: {node: :em}}

Configuring styles

PortableText::Html.config.block.styles.merge!{h1: {node: :h3,class: "header"}}# Defaults{h1: {node: :h1},h2: {node: :h2},h3: {node: :h3},h4: {node: :h4},h5: {node: :h5},h6: {node: :h6},blockquote: {node: :blockquote},normal: {node: :p},li: {node: :li}}

Configuring list types

PortableText::Html.config.block.list_types.merge!{bullet: {node: :div}}# Defaults{bullet: {node: :ul},numeric: {node: :ol}}

Adding a new serializer

You can add a new serializer by creating a new class. You then need to add it the the config.

The serializer needs to have a content method and takes a list of blocks as only parameter.

classMySerializerdefinitialize(blocks)@blocks=blocksenddefcontent(**options)blocks.map |block|
block.type + " - " + block.key + " - " + options[:context]end.join(" ")endendPortableText.config.serializers.merge!{my_serializer: MySerializer}content=[{"_key": "12345ffxx","_type": "block", ... }]serializer=PortableText::Serializer.new(content: content,to: :my_serializer)# render forwards any keyword argument to the content method in the serializerserializer.render(context: "readme")# => block - 12345ffxx - readme

Acknowledgments

Thanks to Joel Drapper and Will Cosgrove for their help in building the HTML serializer!

Ruby Portable Text

A ruby library to render Portable text

This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.

You can:

easily render default PortableText blocks in html without any configuration
create custom block types, mark_defs. Add them or replace existing ones.
create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
customize each HTML node with custom attributes
create a new serializer

This is a very early release so please open issues if something doesn't work as intended.

Installation

gem install portable_text

Usage

See Rails usage for usage in rails

PortableText::Serializer takes 2 parameters:

content: , the portable text Array
to: , the rendering format. It defaults to: :html

You can also use the :plain rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.

PortableText accepts 2 methods, render and convert!.

render renders the content to the specified format defined in the to parameter. See How to render html ? for more information.
convert! converts the content to be used by the library.
- It is useful for debugging purposes.
- It transforms the keys to ruby format.
- It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.

How to render html?

Under the hood, the html renderer uses Phlex, a templating language which allows to create html in plain ruby.

content=[{"_key": "12345ffxx","_type": "block","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Hello world!"}],"markDefs": [],"style": "h1"}]portable_text=PortableText::Serializer.new(content: content,to: :html)# Since the HTML renderer uses Phlex, you can either include the rendering module # and use the render method...includePortableText::Html::Renderingrenderportable_text.render# => <h1>Hello world!</h1># ... Or you can directly call the Phlex templateportable_text.render.call# => <h1>Hello world!</h1>

Rails usage

To use the PortableText HTML serializer in rails, you need to add phlex-rails to the Gemfile.

You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.

gem'portable_text'gem'phlex-rails'

Then run bundle install

Then, in a controller or a view, just use render as usual.

portable_text=PortableText::Serializer.new(content: content,to: :html)renderportable_text.render

Configuration

This library is highly customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.

Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.

So, in order to use a block type or a mark definition, one has to:

register it in the PortableText configuration, so it can be passed as an object to the serializer
create the template in the serializer (see HTML configuration)

Registering block types

content=[{"_key": "12345ffxx","_type": "myType", ...,"url": "https://www.github.com","image_url": "https://www.myimage.com/my_image.jpg","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Github"}]}]# Under the hood, this library uses dry-initializer.# You can use the option method to configure it easilyclassMyBlock < PortableText::BlockTypes::Baseoption:url,default: proc{""}option:image_url,default: proc{""}# children is an inherited option so it does not need to be added hereend# Or use plain old ruby. It needs to have attr_readers!classMyBlock < PortableText::BlockTypes::Baseattr_reader:url,:image_urldefinitialize(url: "",image_url:, **)super@url=url@image_url=image_urlendend# PortableText transforms keys to ruby format so use conventional ruby!# myType becomes my_type.PortableText.config.block.types.merge!{my_block: MyBlock}

Default block types

It’s probably a good idea to leave the list block type untouched. Change at your own risk.

{block: BlockTypes::Block,image: BlockTypes::Image,list: BlockTypes::List,span: BlockTypes::Span}

Registering mark definitions

It’s very similar to registering blocks. In case of doubt, refer to the block documentation.

content=[{"_key": "12345ffxx","_type": "block", ...,"markDefs": [{"_key"=>"456","_type"=>"newMarkDef"}],}]classNewMarkDef < PortableText::MarkDefs::Baseoption:label,default: proc{""}endPortableText.config.block.mark_defs.merge!{new_mark_def: NewMarkDef}

Html Serializer configuration

After registering your block type or mark definition, you need to create its template.

Each template takes one argument, a block.

Block Type Template

# Let's use the block defined earlier in Registering block typesclassHtml::MyBlock < PortableText::Html::BaseComponent# You can include PortableText::Html::Configured # to get access to the html serializer configuration helpers# The #config method allows you to access config values # The #block_type(:key) method is a shortcut to the relevant block_typeincludePortableText::Html::Configured# This library uses dry-initializer # so you can use `param` to create a simple parameter# There is no attribute_reader so `param :my_block` generates `@my_block`# This is recommended because some common HTML method names could conflict with# Phlex methods, like `title`. param:my_blockdefview_templatedivdoimg(src: @my_block.image_url)linkendendprivatedeflinka(href: @my_block.url)do@my_block.children.eachdo |child|
renderblock_type(:span).new(child,mark_defs: nil)endendendend# It needs to have the same key as the one registered before.PortableText::Html.config.block.types.merge!{my_block: Html::MyBlock}

Mark Definition template

Each mark definition takes one argument, a mark definition registered in the configuration.

# Let's use the mark definition defined earlier in Registering mark definitionclassHtml::NewMarkDef < PortableText::Html::BaseComponentparam:mark_def# &block is mandatory because mark definitions always contain other nodesdefview_template(&block)a(href: @mark_def.url){block.call}endend# It needs to have the same key as the one registered before.PortableText::Html.config.block.mark_defs.merge!{new_mark_def: Html::NewMarkDef}

Customizing html nodes

Every HTML node is customizable through config and looks this way:

h1: { node: :h1 }

You can add HTML attributes by appending them. For example:

h1: {node: :h1,class:"header"}

Configuring marks

You can configure marks by updating the marks setting.

PortableText::Html.config.span.marks.merge!{strong: {node: :b,}}# Defaults{strong: {node: :strong},em: {node: :em}}

Configuring styles

PortableText::Html.config.block.styles.merge!{h1: {node: :h3,class: "header"}}# Defaults{h1: {node: :h1},h2: {node: :h2},h3: {node: :h3},h4: {node: :h4},h5: {node: :h5},h6: {node: :h6},blockquote: {node: :blockquote},normal: {node: :p},li: {node: :li}}

Configuring list types

PortableText::Html.config.block.list_types.merge!{bullet: {node: :div}}# Defaults{bullet: {node: :ul},numeric: {node: :ol}}

Adding a new serializer

You can add a new serializer by creating a new class. You then need to add it the the config.

The serializer needs to have a content method and takes a list of blocks as only parameter.

classMySerializerdefinitialize(blocks)@blocks=blocksenddefcontent(**options)blocks.map |block|
block.type + " - " + block.key + " - " + options[:context]end.join(" ")endendPortableText.config.serializers.merge!{my_serializer: MySerializer}content=[{"_key": "12345ffxx","_type": "block", ... }]serializer=PortableText::Serializer.new(content: content,to: :my_serializer)# render forwards any keyword argument to the content method in the serializerserializer.render(context: "readme")# => block - 12345ffxx - readme

Acknowledgments

Thanks to Joel Drapper and Will Cosgrove for their help in building the HTML serializer!

Ruby Portable Text

A ruby library to render Portable text

This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.

You can:

easily render default PortableText blocks in html without any configuration
create custom block types, mark_defs. Add them or replace existing ones.
create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
customize each HTML node with custom attributes
create a new serializer

This is a very early release so please open issues if something doesn't work as intended.

Installation

gem install portable_text

Usage

See Rails usage for usage in rails

PortableText::Serializer takes 2 parameters:

content: , the portable text Array
to: , the rendering format. It defaults to: :html

You can also use the :plain rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.

PortableText accepts 2 methods, render and convert!.

render renders the content to the specified format defined in the to parameter. See How to render html ? for more information.
convert! converts the content to be used by the library.
- It is useful for debugging purposes.
- It transforms the keys to ruby format.
- It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.

How to render html?

Under the hood, the html renderer uses Phlex, a templating language which allows to create html in plain ruby.

content=[{"_key": "12345ffxx","_type": "block","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Hello world!"}],"markDefs": [],"style": "h1"}]portable_text=PortableText::Serializer.new(content: content,to: :html)# Since the HTML renderer uses Phlex, you can either include the rendering module # and use the render method...includePortableText::Html::Renderingrenderportable_text.render# => <h1>Hello world!</h1># ... Or you can directly call the Phlex templateportable_text.render.call# => <h1>Hello world!</h1>

Rails usage

To use the PortableText HTML serializer in rails, you need to add phlex-rails to the Gemfile.

You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.

gem'portable_text'gem'phlex-rails'

Then run bundle install

Then, in a controller or a view, just use render as usual.

portable_text=PortableText::Serializer.new(content: content,to: :html)renderportable_text.render

Configuration

This library is highly customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.

Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.

So, in order to use a block type or a mark definition, one has to:

register it in the PortableText configuration, so it can be passed as an object to the serializer
create the template in the serializer (see HTML configuration)

Registering block types

content=[{"_key": "12345ffxx","_type": "myType", ...,"url": "https://www.github.com","image_url": "https://www.myimage.com/my_image.jpg","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Github"}]}]# Under the hood, this library uses dry-initializer.# You can use the option method to configure it easilyclassMyBlock < PortableText::BlockTypes::Baseoption:url,default: proc{""}option:image_url,default: proc{""}# children is an inherited option so it does not need to be added hereend# Or use plain old ruby. It needs to have attr_readers!classMyBlock < PortableText::BlockTypes::Baseattr_reader:url,:image_urldefinitialize(url: "",image_url:, **)super@url=url@image_url=image_urlendend# PortableText transforms keys to ruby format so use conventional ruby!# myType becomes my_type.PortableText.config.block.types.merge!{my_block: MyBlock}

Default block types

It’s probably a good idea to leave the list block type untouched. Change at your own risk.

{block: BlockTypes::Block,image: BlockTypes::Image,list: BlockTypes::List,span: BlockTypes::Span}

Registering mark definitions

It’s very similar to registering blocks. In case of doubt, refer to the block documentation.

content=[{"_key": "12345ffxx","_type": "block", ...,"markDefs": [{"_key"=>"456","_type"=>"newMarkDef"}],}]classNewMarkDef < PortableText::MarkDefs::Baseoption:label,default: proc{""}endPortableText.config.block.mark_defs.merge!{new_mark_def: NewMarkDef}

Html Serializer configuration

After registering your block type or mark definition, you need to create its template.

Each template takes one argument, a block.

Block Type Template

# Let's use the block defined earlier in Registering block typesclassHtml::MyBlock < PortableText::Html::BaseComponent# You can include PortableText::Html::Configured # to get access to the html serializer configuration helpers# The #config method allows you to access config values # The #block_type(:key) method is a shortcut to the relevant block_typeincludePortableText::Html::Configured# This library uses dry-initializer # so you can use `param` to create a simple parameter# There is no attribute_reader so `param :my_block` generates `@my_block`# This is recommended because some common HTML method names could conflict with# Phlex methods, like `title`. param:my_blockdefview_templatedivdoimg(src: @my_block.image_url)linkendendprivatedeflinka(href: @my_block.url)do@my_block.children.eachdo |child|
renderblock_type(:span).new(child,mark_defs: nil)endendendend# It needs to have the same key as the one registered before.PortableText::Html.config.block.types.merge!{my_block: Html::MyBlock}

Mark Definition template

Each mark definition takes one argument, a mark definition registered in the configuration.

# Let's use the mark definition defined earlier in Registering mark definitionclassHtml::NewMarkDef < PortableText::Html::BaseComponentparam:mark_def# &block is mandatory because mark definitions always contain other nodesdefview_template(&block)a(href: @mark_def.url){block.call}endend# It needs to have the same key as the one registered before.PortableText::Html.config.block.mark_defs.merge!{new_mark_def: Html::NewMarkDef}

Customizing html nodes

Every HTML node is customizable through config and looks this way:

h1: { node: :h1 }

You can add HTML attributes by appending them. For example:

h1: {node: :h1,class:"header"}

Configuring marks

You can configure marks by updating the marks setting.

PortableText::Html.config.span.marks.merge!{strong: {node: :b,}}# Defaults{strong: {node: :strong},em: {node: :em}}

Configuring styles

PortableText::Html.config.block.styles.merge!{h1: {node: :h3,class: "header"}}# Defaults{h1: {node: :h1},h2: {node: :h2},h3: {node: :h3},h4: {node: :h4},h5: {node: :h5},h6: {node: :h6},blockquote: {node: :blockquote},normal: {node: :p},li: {node: :li}}

Configuring list types

PortableText::Html.config.block.list_types.merge!{bullet: {node: :div}}# Defaults{bullet: {node: :ul},numeric: {node: :ol}}

Adding a new serializer

You can add a new serializer by creating a new class. You then need to add it the the config.

The serializer needs to have a content method and takes a list of blocks as only parameter.

classMySerializerdefinitialize(blocks)@blocks=blocksenddefcontent(**options)blocks.map |block|
block.type + " - " + block.key + " - " + options[:context]end.join(" ")endendPortableText.config.serializers.merge!{my_serializer: MySerializer}content=[{"_key": "12345ffxx","_type": "block", ... }]serializer=PortableText::Serializer.new(content: content,to: :my_serializer)# render forwards any keyword argument to the content method in the serializerserializer.render(context: "readme")# => block - 12345ffxx - readme

Acknowledgments

Thanks to Joel Drapper and Will Cosgrove for their help in building the HTML serializer!

Ruby Portable Text

A ruby library to render Portable text

This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.

You can:

easily render default PortableText blocks in html without any configuration
create custom block types, mark_defs. Add them or replace existing ones.
create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
customize each HTML node with custom attributes
create a new serializer

This is a very early release so please open issues if something doesn't work as intended.

Installation

gem install portable_text

Usage

See Rails usage for usage in rails

PortableText::Serializer takes 2 parameters:

content: , the portable text Array
to: , the rendering format. It defaults to: :html

You can also use the :plain rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.

PortableText accepts 2 methods, render and convert!.

render renders the content to the specified format defined in the to parameter. See How to render html ? for more information.
convert! converts the content to be used by the library.
- It is useful for debugging purposes.
- It transforms the keys to ruby format.
- It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.

How to render html?

Under the hood, the html renderer uses Phlex, a templating language which allows to create html in plain ruby.

content=[{"_key": "12345ffxx","_type": "block","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Hello world!"}],"markDefs": [],"style": "h1"}]portable_text=PortableText::Serializer.new(content: content,to: :html)# Since the HTML renderer uses Phlex, you can either include the rendering module # and use the render method...includePortableText::Html::Renderingrenderportable_text.render# => <h1>Hello world!</h1># ... Or you can directly call the Phlex templateportable_text.render.call# => <h1>Hello world!</h1>

Rails usage

To use the PortableText HTML serializer in rails, you need to add phlex-rails to the Gemfile.

You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.

gem'portable_text'gem'phlex-rails'

Then run bundle install

Then, in a controller or a view, just use render as usual.

portable_text=PortableText::Serializer.new(content: content,to: :html)renderportable_text.render

Configuration

This library is highly customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.

Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.

So, in order to use a block type or a mark definition, one has to:

register it in the PortableText configuration, so it can be passed as an object to the serializer
create the template in the serializer (see HTML configuration)

Registering block types

content=[{"_key": "12345ffxx","_type": "myType", ...,"url": "https://www.github.com","image_url": "https://www.myimage.com/my_image.jpg","children": [{"_key": "78910xxyy","_type": "span","marks": [],"text": "Github"}]}]# Under the hood, this library uses dry-initializer.# You can use the option method to configure it easilyclassMyBlock < PortableText::BlockTypes::Baseoption:url,default: proc{""}option:image_url,default: proc{""}# children is an inherited option so it does not need to be added hereend# Or use plain old ruby. It needs to have attr_readers!classMyBlock < PortableText::BlockTypes::Baseattr_reader:url,:image_urldefinitialize(url: "",image_url:, **)super@url=url@image_url=image_urlendend# PortableText transforms keys to ruby format so use conventional ruby!# myType becomes my_type.PortableText.config.block.types.merge!{my_block: MyBlock}

Default block types

It’s probably a good idea to leave the list block type untouched. Change at your own risk.

{block: BlockTypes::Block,image: BlockTypes::Image,list: BlockTypes::List,span: BlockTypes::Span}

Registering mark definitions

It’s very similar to registering blocks. In case of doubt, refer to the block documentation.

content=[{"_key": "12345ffxx","_type": "block", ...,"markDefs": [{"_key"=>"456","_type"=>"newMarkDef"}],}]classNewMarkDef < PortableText::MarkDefs::Baseoption:label,default: proc{""}endPortableText.config.block.mark_defs.merge!{new_mark_def: NewMarkDef}

Html Serializer configuration

After registering your block type or mark definition, you need to create its template.

Each template takes one argument, a block.

Block Type Template

# Let's use the block defined earlier in Registering block typesclassHtml::MyBlock < PortableText::Html::BaseComponent# You can include PortableText::Html::Configured # to get access to the html serializer configuration helpers# The #config method allows you to access config values # The #block_type(:key) method is a shortcut to the relevant block_typeincludePortableText::Html::Configured# This library uses dry-initializer # so you can use `param` to create a simple parameter# There is no attribute_reader so `param :my_block` generates `@my_block`# This is recommended because some common HTML method names could conflict with# Phlex methods, like `title`. param:my_blockdefview_templatedivdoimg(src: @my_block.image_url)linkendendprivatedeflinka(href: @my_block.url)do@my_block.children.eachdo |child|
renderblock_type(:span).new(child,mark_defs: nil)endendendend# It needs to have the same key as the one registered before.PortableText::Html.config.block.types.merge!{my_block: Html::MyBlock}

Mark Definition template

Each mark definition takes one argument, a mark definition registered in the configuration.

# Let's use the mark definition defined earlier in Registering mark definitionclassHtml::NewMarkDef < PortableText::Html::BaseComponentparam:mark_def# &block is mandatory because mark definitions always contain other nodesdefview_template(&block)a(href: @mark_def.url){block.call}endend# It needs to have the same key as the one registered before.PortableText::Html.config.block.mark_defs.merge!{new_mark_def: Html::NewMarkDef}

Customizing html nodes

Every HTML node is customizable through config and looks this way:

h1: { node: :h1 }

You can add HTML attributes by appending them. For example:

h1: {node: :h1,class:"header"}

Configuring marks

You can configure marks by updating the marks setting.

PortableText::Html.config.span.marks.merge!{strong: {node: :b,}}# Defaults{strong: {node: :strong},em: {node: :em}}

Configuring styles

PortableText::Html.config.block.styles.merge!{h1: {node: :h3,class: "header"}}# Defaults{h1: {node: :h1},h2: {node: :h2},h3: {node: :h3},h4: {node: :h4},h5: {node: :h5},h6: {node: :h6},blockquote: {node: :blockquote},normal: {node: :p},li: {node: :li}}

Configuring list types

PortableText::Html.config.block.list_types.merge!{bullet: {node: :div}}# Defaults{bullet: {node: :ul},numeric: {node: :ol}}

Adding a new serializer

You can add a new serializer by creating a new class. You then need to add it the the config.

The serializer needs to have a content method and takes a list of blocks as only parameter.

classMySerializerdefinitialize(blocks)@blocks=blocksenddefcontent(**options)blocks.map |block|
block.type + " - " + block.key + " - " + options[:context]end.join(" ")endendPortableText.config.serializers.merge!{my_serializer: MySerializer}content=[{"_key": "12345ffxx","_type": "block", ... }]serializer=PortableText::Serializer.new(content: content,to: :my_serializer)# render forwards any keyword argument to the content method in the serializerserializer.render(context: "readme")# => block - 12345ffxx - readme

Acknowledgments

Thanks to Joel Drapper and Will Cosgrove for their help in building the HTML serializer!

Name		Name	Last commit message	Last commit date
bin		bin
lib		lib
sig		sig
test		test
.gitignore		.gitignore
.rubocop.yml		.rubocop.yml
.rubocop_todo.yml		.rubocop_todo.yml
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
Rakefile		Rakefile
portable_text.gemspec		portable_text.gemspec

Name		Name	Last commit message	Last commit date
bin		bin
lib		lib
sig		sig
test		test
.gitignore		.gitignore
.rubocop.yml		.rubocop.yml
.rubocop_todo.yml		.rubocop_todo.yml
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
Rakefile		Rakefile
portable_text.gemspec		portable_text.gemspec

Name		Name	Last commit message	Last commit date
bin		bin
lib		lib
sig		sig
test		test
.gitignore		.gitignore
.rubocop.yml		.rubocop.yml
.rubocop_todo.yml		.rubocop_todo.yml
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
Rakefile		Rakefile
portable_text.gemspec		portable_text.gemspec

Name		Name	Last commit message	Last commit date
bin		bin
lib		lib
sig		sig
test		test
.gitignore		.gitignore
.rubocop.yml		.rubocop.yml
.rubocop_todo.yml		.rubocop_todo.yml
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
Rakefile		Rakefile
portable_text.gemspec		portable_text.gemspec

Name		Name	Last commit message	Last commit date
bin		bin
lib		lib
sig		sig
test		test
.gitignore		.gitignore
.rubocop.yml		.rubocop.yml
.rubocop_todo.yml		.rubocop_todo.yml
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
Rakefile		Rakefile
portable_text.gemspec		portable_text.gemspec

Latest commit

History

Folders and files

Repository files navigation

Ruby Portable Text

Installation

Usage

How to render html?

Rails usage

Configuration

Registering block types

Default block types

Registering mark definitions

Html Serializer configuration

Block Type Template

Mark Definition template

Customizing html nodes

Configuring marks

Configuring styles

Configuring list types

Adding a new serializer

Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Ruby Portable Text

Installation

Usage

How to render html?

Rails usage

Configuration

Registering block types

Default block types

Registering mark definitions

Html Serializer configuration

Block Type Template

Mark Definition template

Customizing html nodes

Configuring marks

Configuring styles

Configuring list types

Adding a new serializer

Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Ruby Portable Text

Installation

Usage

How to render html?

Rails usage

Configuration

Registering block types

Default block types

Registering mark definitions

Html Serializer configuration

Block Type Template

Mark Definition template