Customizing JSON - alleyinteractive/apple-news GitHub Wiki

For advanced users, the Apple News plugin allows you to customize JSON. Each Apple News component that is handled by the plugin has one or more JSON specs for the main component JSON, layouts and/or styles. Some components have multiple specs for each of those if they have different visual appearances in different contexts. Editing these specs allows you to implement more advanced features from Apple News Format than can be handled via theme settings.

To get started, go to Customize JSON from the Apple News menu:

Apple News Menu

Select the theme for which you want to customize JSON.

Next, select the component you wish to edit from the dropdown:

Component JSON dropdown

You will then see a form that shows the editable JSON specs for that component.

Component JSON editing

Some specs will include values in the format #token#. These are tokens that represent dynamic values that will be inserted into the JSON when the post is published to Apple News.

There are three types of tokens:

  • Spec-specific: These will be included with the default spec, and can be removed, but cannot be added to different specs. They are computed at the time that the spec is translated to JSON, and are specific to a particular spec.
  • Postmeta: You can include postmeta values by including a token in the format #postmeta.meta_key# where meta_key is the key of the postmeta that you want to include. Note that this only works on single postmeta values (get_post_meta is called with the $single parameter set to true).
  • Settings: All of the theme settings are available to be included in custom JSON specs. To include a value for a theme setting, simply use #setting_name# where setting_name is the name of the setting you wish to include. The full list of available theme settings for use in tokens is as follows:
    • ad_frequency
    • ad_margin
    • blockquote_background_color
    • blockquote_background_color_dark
    • blockquote_border_color
    • blockquote_border_color_dark
    • blockquote_border_style
    • blockquote_border_width
    • blockquote_color
    • blockquote_color_dark
    • blockquote_font
    • blockquote_line_height
    • blockquote_size
    • blockquote_tracking
    • body_background_color
    • body_background_color_dark
    • body_color
    • body_color_dark
    • body_font
    • body_line_height
    • body_link_color
    • body_link_color_dark
    • body_orientation
    • body_size
    • body_tracking
    • byline_color
    • byline_color_dark
    • byline_font
    • byline_format
    • byline_line_height
    • byline_size
    • byline_tracking
    • caption_color
    • caption_color_dark
    • caption_font
    • caption_line_height
    • caption_size
    • caption_tracking
    • cover_caption
    • dropcap_background_color
    • dropcap_background_color_dark
    • dropcap_color
    • dropcap_color_dark
    • dropcap_font
    • dropcap_number_of_characters
    • dropcap_number_of_lines
    • dropcap_number_of_raised_lines
    • dropcap_padding
    • enable_advertisement
    • gallery_type
    • header1_color
    • header1_color_dark
    • header1_font
    • header1_line_height
    • header1_size
    • header1_tracking
    • header2_color
    • header2_color_dark
    • header2_font
    • header2_line_height
    • header2_size
    • header2_tracking
    • header3_color
    • header3_color_dark
    • header3_font
    • header3_line_height
    • header3_size
    • header3_tracking
    • header4_color
    • header4_color_dark
    • header4_font
    • header4_line_height
    • header4_size
    • header4_tracking
    • header5_color
    • header5_color_dark
    • header5_font
    • header5_line_height
    • header5_size
    • header5_tracking
    • header6_color
    • header6_color_dark
    • header6_font
    • header6_line_height
    • header6_size
    • header6_tracking
    • initial_dropcap
    • layout_gutter
    • layout_margin
    • layout_width
    • monospaced_color
    • monospaced_color_dark
    • monospaced_font
    • monospaced_line_height
    • monospaced_size
    • monospaced_tracking
    • pullquote_border_color
    • pullquote_border_color_dark
    • pullquote_border_style
    • pullquote_border_width
    • pullquote_color
    • pullquote_color_dark
    • pullquote_font
    • pullquote_hanging_punctuation
    • pullquote_line_height
    • pullquote_size
    • pullquote_tracking
    • pullquote_transform
    • recipe_background_color
    • recipe_background_color_dark
    • recipe_body_background_color
    • recipe_body_background_color_dark
    • recipe_body_color
    • recipe_body_color_dark
    • recipe_body_font
    • recipe_body_line_height
    • recipe_body_link_color
    • recipe_body_link_color_dark
    • recipe_body_size
    • recipe_body_tracking
    • recipe_caption_color
    • recipe_caption_color_dark
    • recipe_caption_font
    • recipe_caption_line_height
    • recipe_caption_link_color
    • recipe_caption_link_color_dark
    • recipe_caption_size
    • recipe_caption_tracking
    • recipe_details_background_color
    • recipe_details_background_color_dark
    • recipe_details_color
    • recipe_details_color_dark
    • recipe_details_font
    • recipe_details_line_height
    • recipe_details_link_color
    • recipe_details_link_color_dark
    • recipe_details_size
    • recipe_details_tracking
    • recipe_header2_color
    • recipe_header2_color_dark
    • recipe_header2_font
    • recipe_header2_line_height
    • recipe_header2_size
    • recipe_header2_tracking
    • recipe_header3_color
    • recipe_header3_color_dark
    • recipe_header3_font
    • recipe_header3_line_height
    • recipe_header3_size
    • recipe_header3_tracking
    • recipe_header4_color
    • recipe_header4_color_dark
    • recipe_header4_font
    • recipe_header4_line_height
    • recipe_header4_size
    • recipe_header4_tracking
    • recipe_title_color
    • recipe_title_color_dark
    • recipe_title_font
    • recipe_title_line_height
    • recipe_title_size
    • recipe_title_tracking
    • table_body_background_color
    • table_body_background_color_dark
    • table_body_color
    • table_body_color_dark
    • table_body_font
    • table_body_horizontal_alignment
    • table_body_line_height
    • table_body_padding
    • table_body_size
    • table_body_tracking
    • table_body_vertical_alignment
    • table_border_color
    • table_border_color_dark
    • table_border_style
    • table_border_width
    • table_header_background_color
    • table_header_background_color_dark
    • table_header_color
    • table_header_color_dark
    • table_header_font
    • table_header_horizontal_alignment
    • table_header_line_height
    • table_header_padding
    • table_header_size
    • table_header_tracking
    • table_header_vertical_alignment

When you have finished editing, click the Save JSON button. The new specs will now be used for that component when publishing posts to Apple News using the selected theme moving forward.

The following components and JSON specs are supported:

Advertisement

JSON

The main component JSON.

Layout

The default component layout.

Audio

JSON With Caption Text

The main component JSON, which is used when a caption is present.

JSON

The main component JSON.

Body

JSON

The main component JSON.

Layout

The default component layout.

Layout for Last Component

Layout settings for the last body component only.

Default Style

The default component style.

Drop Cap Style

The style for the first body component when drop caps are enabled.

Byline

JSON

The main component JSON.

Style

The default component style.

Layout

The default component layout.

Cover

JSON

The main component JSON.

JSON with Caption

The main component JSON, which is used when a caption is present.

Layout

The default component layout.

Layout with Caption

The default component layout, which is used when a caption is present.

Below Text Layout

The component layout to use when the cover is positioned below text.

Divider

JSON

The main component JSON.

Layout

The default component layout.

Embed Generic

JSON

The main component JSON.

Layout

The default component layout.

Embed Web Video (Youtube/Vimeo)

JSON

The main component JSON.

Layout

The default component layout.

End of Article

This is a special component that is automatically inserted at the end of each article rendered by this theme. You can add whatever content you like, as long as it is valid Apple News Format. Typical use cases here would be calls to action for things like subscribing to newsletters.

JSON

The main component JSON. Defaults to nothing, in which case no End of Article module will appear. You may insert whatever you like here.

Layout

The default component layout. Defaults to nothing, in which case there will be no layout applied. You may insert whatever you like her.

Facebook

JSON

The main component JSON.

Gallery

JSON

The main component JSON.

Layout

The default component layout.

Heading

JSON

The main component JSON.

Layout

The default component layout.

Level 1 Style

The style for level 1 (H1) components.

Level 2 Style

The style for level 2 (H2) components.

Level 3 Style

The style for level 3 (H3) components.

Level 4 Style

The style for level 4 (H4) components.

Level 5 Style

The style for level 5 (H5) components.

Level 6 Style

The style for level 6 (H6) components.

Image

JSON without caption

Main component JSON for images without captions.

JSON with caption

Main component JSON for images with captions.

Anchored Layout

Layout for images that are anchored to another component.

Non-anchored Layout

Layout for images that are not anchored to another component.

Non-anchored with Full Bleed Images Layout

Layout for images that are not anchored to another component when full bleed images are enabled.

Instagram

JSON

The main component JSON.

Intro

JSON

The main component JSON.

Style

The default component style.

Link Button

JSON

The main component JSON.

Button Layout

The default component style.

Link Button Style

Styles for the button itself.

Link Button Text Style

Styles for the text in the button.

Quote

Blockquote Without Border JSON

Main component JSON when borders are not enabled for blockquotes in the theme.

Blockquote With Border JSON

Main component JSON when borders are enabled for blockquotes in the theme.

Blockquote Layout

The default blockquote layout.

Blockquote Style

The default blockquote style.

Pull quote Without Border JSON

Main component JSON when borders are not enabled for blockquotes in the theme.

Pull quote With Border JSON

Main component JSON when borders are enabled for blockquotes in the theme.

Pull quote Layout

The default blockquote layout.

Pull quote Style

The default blockquote style.

Recipe

JSON

The main component JSON for Recipe components generated from JSON-LD data.

Recipe Body Layout

Layout for recipe body text.

Recipe Body Text Style

Style for recipe body text.

Recipe Header 2 Layout

Layout for subheadings in recipes.

Recipe Header 2 Text Style

Style for subheadings in recipes.

Recipe Header 3 Layout

Layout for subheadings in recipes.

Recipe Header 3 Text Style

Style for subheadings in recipes.

Recipe Header 4 Layout

Layout for subheadings in recipes.

Recipe Header 4 Text Style

Style for subheadings in recipes.

Recipe Details Layout

Layout for recipe details like prep time.

Recipe Details Text Style

Layout for recipe details like prep time.

JSON for a Section of Recipe Instructions

Component JSON for a single section of instructions in a multi-section set of instructions.

JSON for a Step Within a Section of Recipe Instructions

Component JSON for a single step in a multi-section set of instructions.

JSON for a Standalone Step in Recipe Instructions

Component JSON for a single step in a flat list of instructions.

JSON for a Wrapper Only

Component JSON used when "Build Recipe Component From Structured Data" is set to "no."

Table

JSON

The main component JSON.

JSON With Caption Text

The main component JSON, which is used when a caption is present.

Table Layout

The default component layout.

Table Style

The default component style.

Title

JSON

The main component JSON.

Style

The default component style.

Layout

The default component layout.

Tweet

JSON

The main component JSON.

Layout

The default component layout.

Video

JSON With Caption Text

The main component JSON, which is used when a caption is present.

JSON

The main component JSON.