https://github.com/frontarm/doc
A set of components for creating rich, responsive documents built around MDX.
https://github.com/frontarm/doc
Last synced: 14 days ago
JSON representation
A set of components for creating rich, responsive documents built around MDX.
- Host: GitHub
- URL: https://github.com/frontarm/doc
- Owner: frontarm
- Created: 2018-12-12T10:24:10.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-02-26T02:39:56.000Z (about 3 years ago)
- Last Synced: 2024-04-29T02:43:47.399Z (12 months ago)
- Language: TypeScript
- Size: 4.58 MB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
@frontarm/doc
==================
> A set of components for creating rich, responsive documents built around MDX.
[](https://www.npmjs.com/package/@frontarm/doc) [](https://standardjs.com)
## Install
```bash
npm install --save @frontarm/doc
```
Design notes
-----
- Styles are designed with the assumption that there'll be 250px of sidebar on windows with width of 1101px or up.
- This library is pretty raw, and you can break things by messing with the styles on
blocks, asides, and gutters. Unfortunately, you need can't escape messing with the styles on blocks.
so think of this more as a shitty but useful tool for creating websites with documents with a
two-column layout -- not a self-contained library that is useful for specifying documents without
any other work. You *will* probably need to use media queries in your theme. You *will* need to
be careful of your use of "margin". Global margin styles *will* make your life miserable.
Main Components
---------------
### ``
Expects an MDX component as its `MDXComponent` prop.
Like MDX components, the components that are used to render each type of Document component can be configured, either by passing in a `components` object to your `` component, or by using a `` component.
#### `props
- `MDXComponent`
The MDX Document component to render.
- `props?: any`
Props that will be passed through to the rendered MDXComponent
- `demoboardHelpers?: { [name: string]: string }`
Helper files that will be available to all inline demoboards
- `canAccessRestrictedContent?: boolean`
If true, any editors/videos with the `isRestricted` attribute will be usable
- `isStatic?: boolean`
If true, any nested `` blocks will not be shown.
### ``
Merges in default values for the `components` object of any child `` elements.
Content Components
------------------
### ``
Indicates content that helps the reader from hurting themselves or losing a large amount of time.
Assumes placement within the left column.
### ``
Renders an inline demoboard.
#### `props`
- `persistenceKey`
If present, any changes will be saved for each user, and loaded when the user navigates back to the page. This key will not be visible to the user, and should be unique across the entire site. It should follow the format `path#keyWithinPage`. A warning will be logged if the path doesn't map to the current path, or if multiple keys are used on the same page.
- `restricted`
If true, readers won't be able to use the demoboard unless `canAccessRestrictedContent` is also passed to the parent `` element.
- `sources`
Accepts a list of sources, with magic sources prefixed by `magic:`, and solution sources prefixed by `solution:`.
*Future plan: create a loader that allows an entire directory to be smashed in here with a single `require()`...*
- `theme?: "dark" | "light"`
- `maximizeLeftPanel?: boolean`: *defaults to `true`*
- `maximizeRightPanel?: boolean`: *defaults to `false`*
- `leftPanel?: 'transformedSource' | 'solutionSource'`
- `lineCount?: number`
- `rightPanel?: 'console'`
- `tab?: 'editor' | 'viewer'`
### ``
Can be placed in either the left or right columns.
### ``
Assumes placement within the left column.
### ``
Assumes placement within the right column.
### ``
Can be placed anywhere; the left column, right column, both columns or full width are all allowable.
#### `props`
- `TODO`
- `restricted`
If true, readers won't be able to use the demoboard unless `canAccessRestrictedContent` is also passed to the parent `` element.
Layout Components
-----------------
Layout components are not configurable
### ``
Renders a block of content in the left column.
### ``
Floats a block of content right of the following columns, similar to how floats in CSS work, but
can be raise up to the position of the top of the wrapping `` div.
```
TODO: format this info better:
"Block" (gutterless?):
- center align on single column
- left align on twin column
- add a gutter (i.e. minimum left/right spacing around the element) if one isn't specified around it,
unless "gutterless?" is specified.
- can *not* have margins added to it, as content needs to have left/right margin of "auto"
to accomodate horizontal centering without a container, which would (I think) break floated asides
and full width stuff
"Aside"/"Float":
- will center align on single column, with extra spacing compared to "Block" to accomodate a gutter
- will float right on twin column
- can only have margins added to it when not centered.
- nested "Block" will have a gutter added, but it can be wrapped in other
styles and have margins added
"Gutter" (half?) (left?) (right?):
- add a minimum left/right spacing around the element
- can not have margins added to it
- is useful for adding spacing around full-width and aside elements
- nested "Block" will have its gutter replaced by this block
```
Conditional Rendering Components
--------------------------------
### ``
Hides its children when the document is being statically built -- useful for parts of the document that vary between guest and pro members.
### ``
Show the children only when the viewer has full access to the Doc. If the viewer doesn't have full access, show the `restricted` element instead.
Code blocks
-----------
When Markdown code blocks begin with the line `//---`, they'll be turned into `` elements. Otherwise, they'll be treated as code listings, which are rendered with the standard `codeBlock` component.
Demoboard code blocks will be split into sections denoted by `//---`. The first section contains configuration that will be passed as props to the `` component. The following sections will be treated differently depending on how they start:
- `--- filename`
Treats the following lines as a source file with the specified filename
- `--- filename <-- helperFilename`
Creates a file, solution or magic file from the helper with the given name.
### Example
```jsx
//---
// name: "Demoboard name"
// description: "Some description about this demoboard"
// isRestricted: true // if true, this will be hidden unless
// defaultRightPanel: "console"
// consoleIsMaximized: false
// defaultViewerURL: ''
//--- main.js
const isDone = false
//--- helper:main.js
const isDone = true
//--- magic:package.json
{
name: "magicFile",
description: "built but not displayed in tabs"
}
//--- styles.css <-- styles-a.css
.test {
/**
* Helpers allow files to be shared between demoboards
*/
}
```
Note that while this inline syntax is great for small, quick examples, for bigger examples you might find it easier to manually add a `` element.
`components` object
-------------------
The `components` object can be passed to an individual ``, or can be passed to a `` to set the default components for all child documents. It supports all MDX compnents, along with a number of document-specific components.
- ``
Like the MDX `wrapper` component, but also receives any `className`, `style` and `id` that were passed to the `` element itself.
- ``
A link within heading elements that points to the heading itself.
### Content components
- `Beware`
- `Demoboard`: *also includes a `hasAccess` boolean*
- `Details`
- `Spoiler`
- `Tangent`
- `Video`: *also includes a `hasAccess` boolean*
## License
MIT © [James K Nelson](https://frontarm.com)