Svelte component library including Mdsvex preprocessor to support creating complex webpages focusing on data visualisation.
npm install vismarkA lightweight libary for creating webpages in Svelte projects. Vismark allows for defining complex layouts and data visualisations using extended Markdown syntax. Available on npm as vismark.
Example pages created with Vismark can be found at Vismark Examples.
``bash`
npm install vismark
This will add all the needed dependencies as well.
Next, you will need to add vismark as the preprocessor in the svelte.confg.js file in the root of your project. Import the vismarkConfig() function from vismark/config and wrap the current Svelte config in it. For example, a simple Svelte project created with npx sv create my-app, would need to be edited in the following way:
`JavaScript
import { vismarkConfig } from 'vismark/config';
// other imports
const config = vismarkConfig({
// leave existing config as is
});
`
Vismark allows you to write webpages in extended Markdown syntax. In order to do this, you can write up your wepage in a file using the .vismd extension.
These pages then need to be added to a +page.svelte as a regular Svelte component. This means if I write a page called AboutMe.vismd, then I can make sure it is actually reflected in the codebase by adding the following to the +page.svelte:
`html
`
A repository showcasing some example wpbages created with Vismark can be found at Vismark Examples
More information on adding pages in Svelte can be found in the Svelte routing docs.
Additional support is also available for footnotes and maths formulae formatting.
) and surrounding it with square brackets. An example is given below:`markdown
Here's the main text with a footnote[^1].[^1]: This is the first footnote.
`$3
In order to render maths formulae nicely, the KaTeX library is used. A list of supported maths symbols and notation can be found in the KaTeX docs. The maths must then be placed inside either:- Single dollar signs (
$), e.g. $E = mc^2$ for inline display.
- Surrounded by three backticks and specifying 'math' for maths on a new line:
`math
E = mc^2
`
- Double dollar signs (
$$), for centered maths formulae:
`
$$
E = mc^2
$$
`Components
Components are entities on a webpage that Markdown cannot define. Every component used in a
.vismd file needs to be imported. This can be done by adding the code below to the .vismd file:`html
`Then this component can be placed on the webpage, either with the
or syntax. Listed below are all components that Vismark supports along with an example of how to use it.$3
Chart components will start with a capital letter and be added to the page using the following syntax:
`svelte
`The variables will allow you to parameterise the chart by defining a title, x and y variables and the path to the dataset used. All data must be in Comma-Separated Values (CSV) format.
#### Example data
Sample data can be found here if you want to follow along with the examples here.
#### Area Chart
Variables:
-
dataPath (String) - path to the data
- xData (String) - name of column that contains the x values
- yData (String) - name of column that contain the y values
- fillData (String) - name of column containing the data for colouring the chart markers
- titleData (String) - title of the chartExample usage:
`html
dataPath="/data/unemployment.csv"
xData="date"
yData="unemployed"
fillData="industry"
titleData="Unemployement over time"
/>
`#### Bar Chart
Variables:
-
dataPath (String) - path to the data
- xData (String) - name of column that contains the x values
- yData (String) - name of columns that contain the y values
- fillData (String) - name of column containing the data for colouring the chart markers
- groupBy (String) - name of the column containing the facets to partition the bars into groups
- titleData (String) - title of the chartExample usage:
`svelte
dataPath="data/population-state-age.csv"
xData="key"
yData="population"
fillData="key"
groupBy="state"
titleData="Population age for 6 US states"
/>
`#### Box Plot
Variables:
-
dataPath (String) - path to the data
- xData (String) - name of column that contains the x values
- yData (String) - name of column that contain the y values
- fillColour (String) - name or value of the colour of the boxes in the plot
- titleData (String) - title of the chartExample usage:
`svelte
dataPath="data/morley.csv"
xData="Expt"
yData="Speed"
fillColour="#eb66a7"
titleData="Speed of Light - Morley Experiment"
/>
`#### Histogram
Variables:
-
dataPath (String) - path to the data
- xData (String) - name of column that contains the x values
- yData (String) - name of column that contain the y values
- fillData (String) - name of column containing the data for colouring the chart markers
- titleData (String) - title of the chartExample usage:
`svelte
dataPath="data/olympians.csv"
xData="weight"
yData="count"
fillData="sex"
titleData="Olympic athletes by weight"
/>
`#### Line Chart
Variables:
-
dataPath (String) - path to the data
- xData (String) - name of column that contains the x values
- yData (String) - name of column that contain the y values
- fillData (String) - name of column containing the data for colouring the chart markers
- titleData (String) - title of the chartExample usage:
`svelte
dataPath="data/unemployment.csv"
xData="date"
yData="unemployed"
fillData="industry"
titleData="Unemployment by industry over time"
/>
`#### Scatter Plot
Variables:
-
dataPath (String) - path to the data
- xData (String) - name of column that contains the x values
- yData (String) - name of column that contain the y values
- fillData (String) - name of column containing the data for colouring the chart markers
- titleData (String) - title of the chartExample usage:
`svelte
dataPath="data/penguins.csv"
xData="culmen_length_mm"
yData="culmen_depth_mm"
fillData="species"
titleData="Penguin culmen sizes by species"
/>
`$3
Page elements are components that define larger parts of a page to add expressivity.#### Grid layout
Grid and Cell components are special, as they require opening and closing tags. They define a grid layout by specifying the number of columns in the Grid and using Cells to add content to every part of the grid. The content goes in between the opening and closing tags like so:
and Example usage:
`svelte
Some text and charts here! |
`> [!NOTE]
> Please note that new lines must surround the content within a Grid/Cell.
Variables for the Cell component:
-
hideCell (Boolean, default=false) - If true, the cell background colour and border become white and the cell becomes transparent.Variables for Grid component:
-
columns (Integer, default=2) - number of columns in the grid
- showGrid (Boolean, default=false) - this is a helper option that highlights the outline of the entire grid (useful for development)Once a Grid layout has been defined using
, the Cell components will be added one by one to the right of the previous and after the full width of the grid has been used, the next cell will appear beneath it. For example, if 2 columns are specified the components will appear on the page like this:!Graphical representation of the grid layout with two columns
#### Header & Footer
Currently, the
and components are not parameterisable, but this might change based on user feedback.Example usage:
`svelte
... Some text and charts ...
`#### Image
An image (.jpeg, .png, .svg) with an option to specify its size.
Variables:
-
path (String) - path to the image file
- scale (String) - percentage to scale the image by. (For example, to make the image half the size, specify scale="50%")Example usage:
`svelte
`#### Widget
A widget allows you to style chunks of a page.
Variables:
-
borderColour (String) - colour of the border
- backgroundColour (String) - colour of the background
- badgeType (String) - an optional badge to give additional information on what data is being displayed. The options are:
- totalUK - shows the total benefit/cost for all of the UK
- perCapita - show the cost/benefit per person in each LAD
- relativeCB - Contribution to national benefitsExample usage:
`svelte
Some text and charts here!
`$3
#### Dropdown
A dropdown allows you to click on the arrow...
... to reveal some more details.
Arguments:
-
shownText (String) - The text that is always visible (next to the dropdown arrow icon ▼)Example usage:
`svelte
This is hidden text.
`Previewing the page locally
To preview the page, you can run:
`bash
npm run dev
`Additional stuff
$3
If you are using Visual Studio Code for development, you can add a file association to
.vismd files to see syntax highlighting. Add the snippet below to the settings.json file:`json
"files.associations": {
"*.vismd": "markdown"
}
``Alternatively, add the file association through the UI. Other code editors and IDEs may have similar options.