bow-swift/nef

Export to Carbon

truizlop opened this issue · 1 comments

truizlop commented

Description

Add a rendering mode to export pages of a playground, or sections from them, to images with Carbon. For sections, this is the suggested syntax:

// nef:begin:carbon
enum Result<E, A> {
  case success(A)
  case failure(E)
}
// nef:end

Parameters

Carbon supports the following query parameters to customize the output:

  • Background color: bg=rgba([r]%C[g]%C[b]%C[a]) where [r], [g] and [b] take integer values from 0 to 255, and [a] take floating point values from 0 (fully transparent) to 1.
  • Theme: coloring theme for the image. t=[theme] where [theme] can be one of the following values: 3024-night, blackboard, base16-dark, base16-light, cobalt, dracula, duotone-dark, hopscotch, lucario, material, monokai, night-owl, nord, oceanic-next, one-light, one-dark, panda-syntax, paraiso-dark, seti, shades-of-purple, solarized%20dark, solarized%20light, tomorrow-night-bright, twilight, verminal, yeti, zenburn.
  • Window theme: style of the window. wt=[theme] where [theme] can be one of the following values: none, sharp, bw.
  • Language: l=swift for all our purposes.
  • Vertical and horizontal padding: pv=[padding]px and ph=[padding]px where [padding] is a positive integer.
  • Drop shadow: ds=true or false.
  • Shadow y-offset: dsyoff=[y]px where [y] is a positive integer number.
  • Shadow blur: dsblur=[x]px where [x] is a positive integer number.
  • Window controls: wc=true or false.
  • Line numbers: ln=true or false.
  • Auto adjust width: wa=true or false.
  • Carbon watermark: wm=true or false.
  • Font: fm=[font] where [font] is one of the available fonts (suggested: Fira%20Code).
  • Font size: fs=[size]px where [size] is a positive integer number.
  • Line height: lh=[percentage]%25 where [percentage] is a positive integer number (greater than 100 for correct visualization, default to 133).
  • Export size: es=[x] where [x] can be one of 1x, 2x or 4x.

Behavior

Opening a URL with the parameters above should give us the chance to visualize the code between the nef annotations with the aspect we customized. We need to explore if the image can be extracted automatically and saved to a specific path, allowing us to perform batches of operations generating multiple images.

miguelangel-dev commented

This is a big user story. In order to help us to complete this issue and to help us during the code review, I have split it into 4 issues.

Issues

  • Update the Markdown library to add Carbon render (tracking in #56)
  • Using carbon render connect it to nef set tool script. Automate the task to find the whole playgrounds (in a project), get the whole page inside each playground and export the code snippets for each page. (tracking in #58)
  • Parametrize the carbon's query for customizing the code snippet. (tracking in #57)
  • Update CLI to support nef-carbon-page parametrized. (tracking in #62)
  • Update the documentation: add to README and microsite information about Carbon integration. How to use from CLI and what it is. (tracking in #60)