search

ckRobinson / multi-column-markdown

A plugin for the Obsidian markdown note application, adding functionality to render markdown documents with multiple columns of text.
GNU General Public License v3.0
284 stars 13 forks source link

readme

Multi-Column Markdown

Take your boring markdown document and add some columns to it! With Multi Column Markdown rather than limiting your document layout to a single linear file you can now define blocks of data to be laid out horizontally next to each other. This additional functionality gives you the freedom to structure your notes in more creative ways.


Preview_1


Core Features

Table of Contents


A Word On Live Preview

Live preivew has been supported in Multi-Column Markdown, however cross compatibilty with other plugins, anything that requires interaction (IE: button clicks), and more advanced, non-naitive markdown, Obsidian features may or may not be supported in this mode.

Due to how custom live preview plugins are implemented within CodeMirror6 and hook into Obsidian, I can not guarentee all plugins will render properly within live preview at this point. Plugins that do not render their content immediatly, such as needing to wait for a dataview query, do not render properly.

This plugin was originally intended for use only in Reading mode where plugins have more control over how content is rendered. Most plugins, interactive elements, advanced markdown, and visual stylings will render better and have more cross compatibility in Reading mode.


Usage:

You create a multi-column region by defining the start, settings, column-end, and end tags. EG:


Text displayed above.

--- start-multi-column: ExampleRegion1\ ```column-settings\ number of columns: 2\ largest column: left\ ```

Text displayed in column 1.

--- end-column ---

Text displayed in column 2.

--- end-multi-column

Text displayed below.

Rendered as: Example_1


Syntax Reference

Start a Multi-Column Region:

Each multi-column region must start with either:

--- start-multi-column: A_unique_region_ID\

or

--- multi-column-start: A_unique_region_ID_1\

or

::::: {.columns id=A_unique_region_ID2}\ (See more about Pandoc's fenced divs syntax below.)_

After defining the start tag you must declare an ID for the region. The ID is used to differentiate between different regions if there are multiple in the same document.

Each ID must be unique within the same document or unexpected render issues may occur. An ID may be used across multiple documents so that, for example, you can use the ID "dailynote" in the template used for your Periodic Notes.

By using the "Insert Multi-Column Region" command (more below) the start ID will be pre-set as a randomly generated 4 character string.

You can also use the "Fix Missing IDs" command which will search the currently open document and append random IDs to all regions that are missing one.


Region Settings:

```column-settings\ Any Setting flags (see below)\ ```

```column-settings\ Any Setting flags (see below)\ ```

::::: {.columns id=A_unique_region_ID_2 Any Additional Setting flags (see below)}


End a Column:

--- column-end ---\ --- end-column ---\ --- column-break ---\ --- break-column ---\

::: columnbreak\ :::\ (New line after columnbreak required.)


End Multi-Column Region:

--- end-multi-column\ --- multi-column-end\

:::\ (This end region syntax is only valid when using the Pandoc fenced divs syntax to start a region.)


Pandoc Fenced Divs Support

You can also use Pandoc's fenced divs syntax to define column regions. (For more detail on this syntax see here and here.)

To create a multicolumn region use:

::: columns

\

:::

To define multiple Pandoc regions on the same document, and to define region settings you must use the attributes syntax:

::::: {.columns property=value id=ID_ExampleID}

\

:::::

Not providing an ID will cause regions to not render.

All other settings can be defined within the attributes using the same setting flag names defined below.

What is supported with this syntax:


Number of Columns:

Example:

```column-settings\ Number of Columns: 2\ ```


Column Size:

By default all of the columns will be set to equal size if this option is omitted.
Can define on a per column basis with array syntax: EG: [25%, 75%]

Example:

```column-settings\ Column Size: standard \ ( OR )\ Column Size: [25%, 75%]\ ```


Border:

By default the border is enabled but can be removed with:
Can define on a per column basis with array syntax: EG: [off, on, off]

Example:

```column-settings\ Border: disabled \ ( OR )\ Border: [off, on]\ ```


Shadow:

On by default, can be removed with:

Example:

```column-settings\ Shadow: off \ ```


Column Position or Column Location:

Only used with the single column option.

Example:

```column-settings\ Number of Columns: 1\ Column Position: Left \ ```


Column Spacing:

Used to set the distance between all of the columns.
Can define on a per column basis with array syntax: EG: [5px, 10px]

Example:

```column-settings\ Column Spacing: 5px \ ( OR )\ Column Spacing: [5px, 10px]\ ```


Content Overflow:

Should the columns cut off anything that goes outside the column bounds or should it be scrollable.
Can define on a per column basis with array syntax: EG: [Scroll, Hidden]

Example:

```column-settings\ Overflow: Hidden \ ( OR )\ Overflow: [Scroll, Hidden]\ ```


Alignment:

Choose the alignment of the content in the columns.
Can define on a per column basis with array syntax: EG: [Left, Center]

Example:

```column-settings\ Alignment: Center \ ( OR )\ Alignment: [Left, Center]\ ```


Align Tables to Text Alignment:

Define whether to align tables to the alignment of the text content, see above.
This setting overrides the plugin level alignment definition.

Example:

```column-settings\ Align Tables to Text Alignment: true \ ( OR )\ Align Tables to Text Alignment: off\ ```


Auto Layout

Example:

```column-settings\ Auto Layout: on \ ```


Auto layout regions do not use defined column breaks. Instead these type of multi-column regions will attempt to balance all content equally between the columns. Headings are also attempted to be preserved so that a heading block will not end a column but will instead be moved to the top of the next column with it's corresponding content.

To use this feature set "Auto Layout: true" within the region settings.


Full Document Multi-Column Reflow

Documents can be set to fully reflow into multiple columns while in Reading mode.

Syntax

To enable document reflow use Obsdian's frontmatter to provide the metadata for the file with the following syntax:

EG:

---
Multi-Column Markdown:
  - Number of columns: 3
  - Alignment: [Left, Center, Left]
  - Border: off
---

First line of document.

All settings must be a list underneath the Multi-Column Markdown tag. If obsidian does not parse a valid syntax it will not render. You can use the "Setup Multi-Column Reflow" command to ensure proper syntax.

Features:

Additional Notes:

Known Issues:

Plugin Cross Compatibility.

Not all plugins will be cross compatable within a multi-column region. Depending on the implementation or use case, some plugins will either entierly not render, render incorrectly, or render but be uninteractable. For the most part, due to how Obsidian plugins work, there is little that can be done at this stage to guarentee cross compatibility. And this is even more the case when using Live Preview. You can check the Cross Compatibility sheet for plugins known to work within columns. Anything not on that list has not been tested.

Obsidian Theming

Just as with cross compatibilty above, multi-column regions may be effected by the Obsidian Theme you are running. There is very little non-layout dependent CSS within MCM but some themes may add or remove elements neccessary to properly render the columns. If regions do not render properly in a specific theme, feel free to open an issue and make sure to include what Obsidian theme you are running when describing the problem.


Full Mutli-Column Examples:

Here



Plugin Commands:

You can access the command pallet with ctrl/command - P.

Insert Multi-Column Region

Will create a two column region where the cursor is located with a randomly generated ID and a default settings block created. Anything currently selected will be moved outside the end of the inserted region as to not overwrite any data.


Fix Missing IDs For Multi-Column Regions

Will search the current document for any region start tags that are missing IDs and randomly generate new IDs for each region.


Toggle Mobile Rendering - Multi-Column Markdown

Enables or disables column rendering on mobile devices only.


Setup Multi-Column Reflow

Adds the default multi-column reflow tags and settings to the document frontmatter. Will not overwrite if already defined.



Installation

From Obsidian Community Plugins

You can install this plugin from the Obsidian Community Plugins menu by following these steps:

From GitHub Repository

Download main.js, manifest.json, styles.css from the latest release and add a new directory: [Obsidian-vault]/.obsidian/plugins/multi-column-markdown and add the files to that directory.

If this is your first Obsidian plugin close and reopen Obsidian and then open the settings menu, click the Community plugins tab to the left, ensure Safe mode is disabled, and then enable "Multi-Column Markdown" in the installed plugins list.



Known Issues

Live Preview

Minor Render Issues


Other



Depricated

These syntax options are currently still supported but are being depricated for the newer syntax above.

Code-Block Start Tags

```start-multi-column\ ```

and

```multi-column-start\ ```

This syntax has been entierly depricated due to many compounding issues caused by MCM conflicting with Obsidian syntax. Notes will display an error on each column region until the syntax is updated. You can use the global syntax update featuer within the settings window, or the note specific command "Fix Multi-Column Syntax in File" within the Command Pallete

Start Multi-Column Region:

Settings Regions:

```settings```\ ```column-settings```\ ```multi-column-settings```

End a Column:

End Multi-Column Region:

Change Log

0.9.1

Bug Fixes

0.9.0

Major Changes

Code-Block start regions have been deprecated Due to a combination of issues, this syntax form has had to be entirely deprecated. To make the transition away from that syntax as smooth as possible a command has been added to the Command Pallete "Fix Multi-Column Syntax in Current File" which will update the opened file to the current syntax. A global syntax update command has also been added to the settings panel. Please make sure to create backups of your vault before using the global updater.

Additions

Improvements
Bug Fixes
Known Issues

0.8.3

Bug Fixes

0.8.2

Bug Fixes

0.8.1

Minor Changes

0.8.0

Syntax Example:

---
Multi-Column Markdown:
  - Number of columns: 3
  - Alignment: [Left, Center, Left]
  - Border: off
---

Full Example Here

Older Changes:

Change log

Support Me:

Buy Me A Coffee

Buy Me a Coffee at ko-fi.com