{ "version": "https://jsonfeed.org/version/1", "title": "squido documentation", "home_page_url": "https://squido-docs.markmoffat.com", "feed_url": "https://squido-docs.markmoffat.com/json", "description": "Squido documentation - A dead-simple Node.js static HTML website generator for super fast static websites which are easier to develop, more secure and dirt cheap to host.", "items": [ { "id": "https://squido-docs.markmoffat.com/getting-started/", "content_html": "\"squido\n

What is squido?

\n

squido is a dead simple static website builder which can be hosted anywhere for super fast websites and very little effort.

\n

The idea is to be a no-code setup and have everything you need to run and host a website. You simply do the writing and customization of style and layout.

\n

Installation

\n

Simply install the squido cli module globally in order to build and manage your static site.

\n

From Github (preferred for latest version)

\n
$ npm i -g https://github.com/mrvautin/squido.git\n
\n

From npm

\n
$ npm install -g squido\n
\n

With Yarn

\n
$ yarn global add squido\n
\n

Start from default blog setup

\n
\nWarning: This will overwrite any existing content you've created\n
\n

Make your squido website directory:

\n
$ mkdir my-squido-website\n
\n

Enter your new squido website directory:

\n
$ cd my-squido-website\n
\n

Setup a new squido website from defaults

\n
$ squido new\n
\n

Start from scratch

\n

Make your squido website directory:

\n
$ mkdir my-squido-website\n
\n

Enter your new squido website directory:

\n
$ cd my-squido-website\n
\n

Get started building your squido website structure.

\n

Start from template

\n

The example we will use below is our blog example. There is also a documentation website example you can use.

\n
$ git clone https://github.com/mrvautin/squido-blog-example my-squido-website\n
\n

Replace my-squido-website with your new website directory name

\n

Enter your new squido website directory:

\n
$ cd my-squido-website\n
\n

Run the following command to build, clean, serve and watch for changes:

\n
$ squido serve -b -w -c\n
\n

You can then visit your website here:

\n
http://localhost:4965\n
\n
\n

Clean = removes everything in your /build directory.

\n
\n
\n

Serve = starts a web server so you can view your website.

\n
\n

Without Git

\n

Whilst it's best and easiest (depending on the user) to use squido with Git to manage deployment and source control. If you don't want to use Git you can use our Post Build tasks to easily deploy and manage your website.

\n

Create Git repository

\n
    \n
  1. Create repository:
    2. \n
\n

\"Create

\n
    \n
  1. Set the repository name:
    2. \n
\n

\"Set

\n
    \n
  1. Set public/private:
    2. \n
\n

\"Set

\n
    \n
  1. Finish creating the repository:
    2. \n
\n

\"Set

\n
    \n
  1. Add your new repository to your git remotes:
    2. \n
\n
$ git remote add origin https://github.com/user/repo.git\n
\n
    \n
  1. Check remote is correctly added:
    2. \n
\n
$ git remote -v\n# Verify new remote\n> origin  https://github.com/user/repo.git (fetch)\n> origin  https://github.com/user/repo.git (push)\n
\n
    \n
  1. Create your first post: /source/posts/hello-world.markdown
    2. \n
\n
---\ntitle: Hello World\npermalink: hello-world\ndescription: Hello World\ndate: '2021-03-10 01:59:00'\n---\n
\n
    \n
  1. Add your new files to first commit:
    2. \n
\n
$ git add .\n
\n
    \n
  1. Commit your files/changes:
    2. \n
\n
$ git commit -m "First commit"\n
\n
    \n
  1. Push your changes to your repository:
    2. \n
\n
$ git push\n
\n

Setup the deploy/hosting.

\n

Demos

\n

Blog style: https://squido-blog.markmoffat.com

\n

Documentation style: This website

\n

Traditional website: https://squido.markmoffat.com

\n", "url": "https://squido-docs.markmoffat.com/getting-started/", "title": "Getting started", "summary": "Getting started with squido", "date_modified": "2021-03-10T01:59:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/structure/", "content_html": "

You can start by grabbing everything in the /source directory of here.

\n

The structure will look something like:

\n

\"Folder

\n

The /<source_dir> directory is the default directory for all the source files. You can change by adding another directory in the sourceDir of the config.js file.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
File nameUsage
index.hbsThe root of your website. The first page which will be rendered.
post.hbsWill render the contents of the .markdown files in /<source_dir>/posts
page.hbsDisplayed at /page/x for the pagination of posts
tag.hbsDisplayed at /tag/x for the collection of posts by tag
\n

Your posts go in the /<source_dir>/posts directory. You will have .markdown files for each post/page you want.

\n

The content directory contains the files used for your website. Eg: Stylesheets, images, javascript files etc.

\n", "url": "https://squido-docs.markmoffat.com/structure/", "title": "Structure", "summary": "Getting started with the squido structure", "date_modified": "2021-03-09T01:58:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/usage-commands/", "content_html": "

The CLI comes with a few commands.

\n
Usage: cli [options] [command]\n\nOptions:\n  -V, --version    output the version number\n  -h, --help       output usage information\n\nCommands:\n  build [options]  Builds your website\n  clean            Clean your website build\n  serve [options]  Serves website\n
\n

Build command

\n

The build command has the following options:

\n
Usage: build [options]\n\nBuilds your website\n\nOptions:\n  -c --clean  Cleans build directory\n  -h, --help  output usage information\n
\n

Import command

\n

The import command allows you to import content from external sources. It has the following options:

\n
Usage: import [options]\n\nImport from external sources\n\nOptions:\n  -f, --file <path>  Specify file to import\n  -t, --type <type>  Specify the type of file to import. Eg: wordpress or ghost\n  -h, --help         output usage information\n
\n

Clean command

\n

The clean command has the following options:

\n
Usage: clean [options]\n\nClean your website build\n\nOptions:\n  -h, --help  output usage information\n
\n

Serve command

\n

The serve command has the following options:

\n
Usage: serve [options]\n\nServes website\n\nOptions:\n  -w --watch  Watches for changes\n  -b --build  Builds on start\n  -c --clean  Cleans build directory\n  -h, --help  output usage information\n
\n

New command

\n

This command sets up a new website from our blog template.

\n
\nWarning: This will overwrite any existing content you've created\n
\n

The new command has the following options:

\n
Usage: new [options]\n\nSets up a new website\n\nOptions:\n  -h, --help  output usage information\n
\n", "url": "https://squido-docs.markmoffat.com/usage-commands/", "title": "Usage / Commands", "summary": "Getting started with the squido commands", "date_modified": "2021-03-08T01:57:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/configuration/", "content_html": "

An example config can be seen below. You can see that you can specify different values for different environments you run. development and production are examples but they need to match up with whatever NODE_ENV is set. If one is not set, the default is development.

\n
const config = {\n    development: {\n        name: 'squido',\n        description: 'This is the blog description',\n        twitterHandle: '@mrvautin',\n        baseUrl: 'http://localhost:4965',\n        sourcesExt: 'markdown',\n        templateEngine: 'hbs',\n        templateConfig: {},\n        sourceDir: 'source',\n        contentDir: 'content',\n        buildDir: 'build',\n        summaryLength: 250,\n        port: 4965,\n        pagination: true,\n        postPerPage: 8\n    },\n    production: {\n        name: 'squido',\n        description: 'This is the blog description',\n        twitterHandle: '@mrvautin',\n        baseUrl: 'http://example.com',\n        sourcesExt: 'markdown',\n        templateEngine: 'hbs',\n        templateConfig: {},\n        sourceDir: 'source',\n        contentDir: 'content',\n        buildDir: 'build',\n        summaryLength: 250,\n        port: 4965,\n        pagination: true,\n        postPerPage: 8,\n        postBuild: [\n            {\n                name: 'zip',\n                options: {}\n            }\n        ]\n    }\n};\n\nmodule.exports = config;\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ConfigUsage
nameUsed in default templates for <title> and meta tags for homepage
descriptionUsed in default templates for meta tags for homepage
baseUrlUsed for URL building purposes. Would set this to https://example.com
sourcesExtThe file extension for your markdown posts
templateEngineThe template engine to use. Possible values are: hbs, ejs or pug
sourceDirThe directory where your markdown posts reside
contentDirThe directory where your Javascript, CSS, images and other assets reside
buildDirThe directory where the static HTML files and assets are placed after building
summaryLengthThe length of the post summary which is available in the meta data of the post
portThe port used when running squido serve
paginationThis controls whether you want squido to paginate your posts
postPerPageThis controls how many posts appear per page
postBuildControls any post build tasks you wish to run. See here
\n

You can use any of the config values in your template files using {{config.<option>}}. Eg: For example {{config.baseUrl}}.

\n

The templateEngine config allows for the setting of which template engine to use - either: hbs, ejs or pug is allowed. The templateConfig object allows for the passing of configurations and is used when ejs or pug is set for the templateEngine. See here for available ejs options and here or pug.

\n", "url": "https://squido-docs.markmoffat.com/configuration/", "title": "Configuration", "summary": "Getting started with the squido configuration", "date_modified": "2021-03-07T01:56:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/posts/", "content_html": "

Posts are essentially pages or blog posts or whatever you like. The content of the post/page is contained in markdown files within the /source/posts folder. The post markdown or contents is rendered using the post.hbs template file. You can edit this any which way your want. See templates for more information.

\n

Posts have a meta data component at the top of the file which directs how the file is built. The meta data is yaml formatted and sits between two --- tags. Eg:

\n
---\ntitle: Caede virides oculos armentis\npermalink: caede-virides-oculos-armentis\ndescription: Caede virides oculos armentis\ndate: '2021-03-11 19:17:00'\ntemplate: post.hbs\nignore: true\nhidden: false\ntags: \n  - alter\n  - tradere\n---\n
\n

Required fields are: 'title', 'permalink', 'description' and 'date'

\n

You can add any data values your like but the example layouts uses the title and description for SEO for page title.

\n

New meta data values can be access in the layouts using {{meta.<new value>}}.

\n

The permalink is required. Its used to build the URL for your website: Eg. The above will output a post at: https://example.com/caede-virides-oculos-armentis

\n

The visible and hidden are optional tags for controlling the visibility of posts. Defaults is "true" or visible.

\n\n

Template file

\n

The default template file name for posts is post.hbs but this can be overwritten per post by adding a template meta value to your post. Eg:

\n
---\ntemplate: template-name.hbs\n---\n
\n", "url": "https://squido-docs.markmoffat.com/posts/", "title": "Posts", "summary": "Getting started with the squido post structure", "date_modified": "2021-03-06T01:55:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/markdown/", "content_html": "

squido uses CommonMark spec to process the markdown formatted posts.

\n

A quick syntax summary to get your started:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TypeRenders
Italic or _Italic_Italic
*Bold* or _Bold_Bold
# Heading 1

Heading 1

# Heading 2

Heading 2

# Heading 3

Heading 3

[Link](https://a.com)Link
[Image](https://url/a.png)\"Link\"
> Blockquote
Blockquote
* List
* List
* List
or
- List
- List
- List
  • List
  • List
  • List
1. List
2. List
3. List
or
1) List
2) List
3) List
  1. List
  2. List
  3. List
Horizontal rule:
---
or
***		Horizontal rule:
`Inline code` with backticksInline code with backticks
``` javascript
const test = () => {
   console.log('test');
};
```
 const test = () => {
   console.log('test');
 };
\n

Playground

\n

You can play around with the Markdown Playground here.

\n

Code syntax highlighting

\n

squido uses Highlight.js for code highlighting. This means you can use the code block example above with code wrapped in ``` backticks. You can specify the language by adding the language for your code block.

\n

For example, adding this:

\n

``` javascript
function test(p1, p2) {
   console.log('test');
};
```

\n

Renders this:

\n
function test(p1, p2) {\n  console.log('test');\n};\n
\n

Markdown helpers

\n

Attributes

\n

You can add any HTML attributes including ID's and classes by adding {attribute} to your Markdown syntax.

\n

Adding a class to a header (style-me is the class):

\n

# header {.style-me}

\n

Adding a data-toggle attribute to a paragraph:

\n

paragraph {data-toggle=modal}

\n

You can also use this on tables with multiple classes. Eg (note the empty line under the table):

\n
My table       | Header                        \n-------------- | ----------\nTable          | Contents\n\n{.table .table-hover .table-bordered}\n
\n

Renders this:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n
My tableHeader
TableContents
\n

Heading anchors

\n

All headings are automatically rendered as # anchors to hyperlink (skip) to sections within a page / post. This means you add the /#heading-name to the URL to automatically jump to that heading.

\n

For example:\nhttps://squido-docs.markmoffat.com/markdown/#playground

\n", "url": "https://squido-docs.markmoffat.com/markdown/", "title": "Markdown", "summary": "Getting started with the squido markdown format", "date_modified": "2021-03-05T01:55:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/templates/", "content_html": "

Templates use Handlebars formatting and the {{}} syntax, EJS or pug. This guide will show Handlebars formatting. Documentation on changing the templateEngine can be found here.

\n
\nThis guide will show examples in Handlebars formatting.\nDocumentation on changing the templateEngine can be found here.\n
\n

The template files needed by default are:

\n\n

Also needed is a layout file called layout.hbs located here: /source/layouts/layout.hbs. This file drives the main layout of the page including the <html>, <head>, <body> etc tags.

\n

Accessible on all layout and templates files is your post meta using {{meta.<property>}} and your config.js object. You can access that using {{config.<propery>}}.

\n

index.hbs

\n

This is the entry point of your website, the index.html in the root of your build directory.

\n

You will have access to a list of posts which you may want to display if building a blog or you may want to manually create a landing page for your website. The choice is yours.

\n

If you were to render your posts you may want to do something like where {{#each posts}} is looping our list of posts:

\n
<div class="row">\n  {{#each posts}}\n  <div class="article">\n    <h2>\n      <a href="/{{this.permalink}}/">{{this.title}}</a> \n    </h2>\n    {{this.summary}}\n  </div>\n  {{/each}}\n</div>\n
\n

Depending on if you have pagination set to true in your config, you will either get a full list of articles or a paginated list. See pagination for more info.

\n

post.hbs

\n

This is the rendering of the post or the markdown content at the permalink set. Eg: mydomain.com/permalink-value.

\n

To render the body of the markdown file you will need to add the following tag to your template: {{{body}}}

\n

You will have access to the full meta values of the page but can also access the title using {{title}}. Depending on whether you included tags in the meta data of the markdown file, you will also get a tags object you can loop through to display tags. See tags for more info.

\n

A simple post page could be:

\n
<div class="row">\n    <div class="col-md-8 offset-md-2 mb-5">\n        <div class="mt-5">\n            <h1>{{title}}</h1>\n            {{{body}}}\n        </div>\n    </div>\n</div>\n
\n

page.hbs

\n

This is the pagination aspect of your website. This template is used at /page/x (where x is the page number). If you are creating a blog which will have pagination this could look very similar to the index.hbs which shows all your articles/posts. Similar to the index.hbs you will get a post object with the posts you should render if you are doing pagination.

\n

A simple template could look like:

\n
<div class="row">\n  {{#each posts}}\n  <div class="col-xs-12 col-sm-3 mb-4 d-flex align-items-stretch">\n    <div class="card shadow-sm">\n      <div class="card-body">\n        <p class="card-text">\n          <h2>\n            <a href="/{{this.permalink}}/">{{this.title}}</a> \n          </h2>\n          {{this.summary}}\n        </p>\n        <div class="d-flex justify-content-between align-items-center">\n          <a class="btn btn-outline-secondary" href="/{{this.permalink}}/">Read more..</a>\n        </div>\n      </div>\n    </div>\n  </div>\n  {{/each}}\n</div>\n
\n

tag.hbs

\n

This is the tag page which is generated from the tags set in your post markdown. A page is create for each tag you use in your markdown files and is accessible at: /tag/<tag-value>. Keep this in mind when setting tag values where you will want to give permalink type values for pretty URLs.

\n

A simple template could look like:

\n
<div class="row">\n  <h1>Tag: {{tag}}</h1>\n  {{#each posts}}\n  <div class="col-xs-12 col-sm-3 mb-4 d-flex align-items-stretch">\n    <div class="card shadow-sm">\n      <div class="card-body">\n        <p class="card-text">\n          <h2>\n            <a href="/{{this.permalink}}">{{this.title}}</a> \n          </h2>\n          {{this.summary}}\n        </p>\n        <div class="d-flex justify-content-between align-items-center">\n          <a class="btn btn-outline-secondary" href="/{{this.permalink}}/">Read more..</a>\n        </div>\n      </div>\n    </div>\n  </div>\n  {{/each}}\n</div>\n
\n

404.hbs

\n

Hopefully this one is obvious. If at any point a page isn't found or a URL is mistyped this 404 page will be rendered.

\n

A simple template:

\n
<div class="row">\n    <div class="col-md-6 offset-md-3 mt-5 mb-3">\n        <div class="text-center">\n            <img src="/content/images/squido.svg" alt="" width="200" height="200" alt="squido logo" class="img-fluid">\n        </div>\n        <h1 class="mt-5 text-center">404 - Page not found</h1>\n    </div>\n</div>\n
\n

Includes

\n

You can include local Stylesheets and Javascript files in the layout.hbs file by using path starting with /content and then wherever you have placed the file. Eg: /content/stylesheets/<myfile>.css.

\n

The layout.hbs also includes a config property named fileEnv ({{config.fileEnv}}) which will return either nothing or .min if you have set the NODE_ENV to production. This is useful if you are wanting to use the un-minified CSS or JS file when troubleshooting/developing your website and using the minified version when in production.

\n

Example usage:

\n
<link rel="stylesheet" href="/content/stylesheets/style{{config.fileEnv}}.css">\n<script src="/content/javascripts/site{{config.fileEnv}}.js"></script>\n
\n

Tags

\n

Within a post you have access to a tag array which contains all the tags for that post. You may want to iterate through that array to link to the /tag/<tag-value> URL. For example:

\n
{{#if tags}}\n<div class="row">\n    <div class="col-md-8 offset-md-2 mb-5">\n        <h5 class="text-muted">Tags:</h5>\n        {{#each tags}}\n        <a href="/tag/{{this}}/">{{this}}</a> |\n        {{/each}}\n    </div>\n</div>\n{{/if}}\n
\n

Pagination

\n

If pagination is set to true in your config.js file, the post object available on all templates will be paginated to the postPerPage value you set in your config.js. Eg: 10 posts and postPerPage set to 5 will create 2 pages. 1, the index page and /page/1 as the first paginated page.

\n

You will also get a shouldPaginate variable which will return true or false depending on whether there is more posts than can be displayed - eg: you should paginate.

\n

An example displaying the pagination might look like:

\n
{{!-- Pagination --}}\n{{#if config.pagination}}\n{{#if shouldPaginate}}\n<div class="row">\n  <div class="col-xs-12 col-sm-12 mb-4 text-center">\n    <p class="text-muted">Page {{page}} of {{pages}}</p>\n    <div class="btn-group" role="group">\n    {{#if prevPage }}\n        <a href="/page/{{prevPage}}/" class="btn btn-outline-secondary">&laquo; Prev Page</a>\n    {{/if}}\n    {{#if nextPage }}\n        <a href="/page/{{nextPage}}/" class="btn btn-outline-secondary">Next Page &raquo;</a>\n    {{/if}}\n    </div>\n  </div>\n</div>\n{{/if}}\n{{/if}}\n
\n

Custom data

\n

squido supports the adding of custom data to your website. This function allows for yaml, json or text formatted files to be parsed and added to the data available in your templates.

\n

Adding custom data is as simple as adding the following Array of Objects to your config.js file. You will need to have the following properties:

\n\n

A full example below:

\n
const config = {\n  development: {\n    name: 'squido',\n    description: 'This is the blog description',\n    twitterHandle: '@mrvautin',\n    baseUrl: 'http://localhost:4965',\n    sourcesExt: 'markdown',\n    templateEngine: 'hbs',\n    data: [\n      {\n        name: 'swagger',\n        type: 'yaml',\n        file: 'swagger.yaml'\n      }\n    ],\n    sourceDir: 'source',\n    buildDir: 'build',\n    ...\n  }\n}\n
\n

Swagger

\n

squido supports Swagger using our custom data functionality. You can use this to setup super fast static API documentation. Simply grab our demo swagger.hbs template and setup a post like the following where template: swagger.hbs is the path to the Swagger template file in your sourceDir:

\n
---\ntitle: Swagger API docs\npermalink: api\ndescription: Swagger API Docs\ndate: '2021-05-11 19:17:00'\ntemplate: swagger.hbs\nvisible: false\nhidden: false\n---\n
\n

Then setup your config.js to include the Swagger data like:

\n
const config = {\n  development: {\n      name: 'squido',\n      description: 'This is the blog description',\n      twitterHandle: '@mrvautin',\n      baseUrl: 'http://localhost:4965',\n      sourcesExt: 'markdown',\n      templateEngine: 'hbs',\n      data: [\n        {\n            name: 'swagger',\n            type: 'yaml',\n            file: 'swagger.yaml'\n        }\n      ],\n      sourceDir: 'source',\n      buildDir: 'build',\n      ...\n    }\n}\n
\n
\n

Where swaggerFile is the name of your swagger.yaml file in relation to your sourceDir. Note: the type can also be set to json for a JSON formatted Swagger file.

\n
\n

Partials

\n

Handlebars

\n

Partials can be created in /source/partials and can be used in layout and other template files.

\n

Once a file is created you can add it to your template using:

\n
{{> header}}\n
\n
\n

Where header is the name of the file header.hbs located: /source/partials/header.hbs

\n
\n

EJS

\n

ejs handling of partials is a little more flexible. You can setup your config using the templateConfig.views option with the directory where the partials will exist. Eg:

\n
const config = {\n  development: {\n      name: 'squido',\n      description: 'This is the blog description',\n      twitterHandle: '@mrvautin',\n      baseUrl: 'http://localhost:4965',\n      sourcesExt: 'markdown',\n      templateEngine: 'ejs',\n      templateConfig: {\n        views: ['source/partials']\n      },\n      sourceDir: 'source',\n      buildDir: 'build',\n      ...\n    }\n}\n
\n
\n

Note: The templateConfig.views takes an array of paths

\n
\n

Pug

\n

Pug partials is super easy. You need to setup the root by setting the templateConfig.basedir to __dirname. Eg:

\n
const config = {\n  development: {\n      name: 'squido',\n      description: 'This is the blog description',\n      twitterHandle: '@mrvautin',\n      baseUrl: 'http://localhost:4965',\n      sourcesExt: 'markdown',\n      templateEngine: 'pug',\n      templateConfig: {\n        basedir: __dirname\n      },\n      sourceDir: 'source',\n      buildDir: 'build',\n      ...\n    }\n}\n
\n

Then in a template you can include a partial by adding the following: include /source/partials/header.pug

\n", "url": "https://squido-docs.markmoffat.com/templates/", "title": "Templates", "summary": "Getting started with the squido templating", "date_modified": "2021-03-04T01:55:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/sitemap-and-feeds/", "content_html": "

A website sitemap is automatically built and can be found at /sitemap.xml. Eg: example.com/sitemap.xml

\n

RSS/Atom/JSON feeds are also automatically built and can be found at:

\n\n", "url": "https://squido-docs.markmoffat.com/sitemap-and-feeds/", "title": "Sitemap and Feeds", "summary": "Getting started with the squido sitemap and feeds", "date_modified": "2021-03-03T01:55:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/plugins/", "content_html": "

Plugins can be created if core functionality is not included or customization is required. Plugins run at the final step of the build so you can override any of the existing steps if needed.

\n

Plugins are Javascript files within /<source dir>/plugins/<plugin name>.js.

\n

The plugin file needs to export a function named run. For example:

\n
const run = (opts) => {\n  /* code in here */\n  console.log('opts', opts);\n};\n\nmodule.exports = {\n  run\n};\n
\n

Configuration

\n

Adding plugins to your /config.js file is simple by adding the plugin to the plugins array:

\n
const config = {\n  development: {\n    ...\n    plugins: [\n      {\n        name: 'search',\n        options: {}\n      }\n    ]\n  }\n}\n
\n

name: the name of the plugin. This also needs to match the name of the file. Eg: /source/plugins/search.js

\n

options: An arg object passed into the plugin.

\n

Environment variables

\n

You can access environment variables in your plugins using the process.squido.envVars object.

\n

You might want to do something different in your plugin based on a environment variable you've set with you hosting provider.

\n

An example plugin:

\n
const run = (opts) => {\n    const config = process.squido;\n\n    let toPrint = 'Hello squido';\n\n    if(config.envVars.helloMessage){\n      toPrint = config.envVars.helloMessage;\n    }\n\n    console.log(`Hello ${toPrint}`);\n};\n\nmodule.exports = {\n    run\n};\n
\n

Eg: For Netlify you would set a variable named helloMessage to World (for example above) and the plugin would then console.log Hello World if the environment variable is set and Hello squido when nothing is set.

\n", "url": "https://squido-docs.markmoffat.com/plugins/", "title": "Plugins", "summary": "Getting started with the squido plugins", "date_modified": "2021-03-02T01:53:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/import-content/", "content_html": "

squido allows the importing of content from Ghost and Wordpress.

\n

We will use the import command.

\n

Ghost

\n

To import data, you first need to export your data from your Ghost site:

\n
    \n
  1. Login to the Ghost admin panel
    2. \n
  2. Select the cog icon at the bottom of the sidebar
    3. \n
  3. Select Labs
    4. \n
  4. Click Export your content
    5. \n
\n

To import that data into squido you need to run this command from the root of your squido website:

\n
$ squido import -f /path/to/file/ghost.json -t ghost\n
\n

You will see a new folder with all your posts in Markdown format here: /imported.

\n

You can check your files are imported correctly then move your newly imported Markdown files here: /<source dir>/posts.

\n

Wordpress

\n

To import data, you first need to export your data from your Wordpress site:

\n
    \n
  1. Login to Wordpress admin panel
    2. \n
  2. Select Tools
    3. \n
  3. Select Export
    4. \n
  4. Click Export all
    5. \n
\n

To import that data into squido you need to run this command from the root of your squido website:

\n
$ squido import -f /path/to/file/wordpress.xml -t wordpress\n
\n

You will see a new folder with all your posts in Markdown format here: /imported.

\n

You can check your files are imported correctly then move your newly imported Markdown files here: /<source dir>/posts.

\n", "url": "https://squido-docs.markmoffat.com/import-content/", "title": "Import content", "summary": "Getting started with the importing content", "date_modified": "2021-03-01T01:53:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/deployment-and-hosting/", "content_html": "

Netlify

\n

You can host this website anywhere static websites are supported. Some options are https://www.netlify.com as the deployments are just dead simple.

\n

Simply connect your Git repo and set the Build settings settings like below:

\n

\"Netlify

\n

And set the Environment variable to align with your config.js file:

\n

\"Netlify

\n

You are done. Now each push to your Git repo will trigger the build and deploy on Netlify.

\n

Github pages

\n

Publishing to Github pages is easy. Simply set your config buildDir to docs and the correct baseUrl. Eg:

\n
production: {\n    name: 'squido',\n    description: 'This is the blog description',\n    twitterHandle: '@mrvautin',\n    baseUrl: 'https://<github-username>.github.io',\n    sourcesExt: 'markdown',\n    sourceDir: 'source',\n    buildDir: 'docs',\n    summaryLength: 250,\n    port: 4965,\n    pagination: true,\n    postPerPage: 8\n}\n
\n

Then simply build your website with squido build -c and push to your Github repo.

\n

You then need to set Source to /docs as shown here and may need to change the branch.

\n

You can then either access at your Repo URL (https://<github-username>.github.io) or a custom domain

\n

Amazon AWS Amplify

\n

It's very easy to publish your squido website to AWS Amplify.

\n
    \n
  1. Login here
    2. \n
  2. Select New App
    3. \n
  3. Select Host web app
    4. \n
  4. Select the Git repository and authenticate. Eg: Github
    5. \n
  5. Select the Repository name and branch from the populated list(s)
    6. \n
  6. Click Edit on the build commands and ensure baseDirectory is set to /build. Eg Yaml file will look like:
    7. \n
\n
version: 1\nfrontend:\n  phases:\n    preBuild:\n      commands:\n        - npm ci\n    build:\n      commands:\n        - npm run build\n  artifacts:\n    baseDirectory: /build\n    files:\n      - '**/*'\n  cache:\n    paths:\n      - node_modules/**/*\n
\n
    \n
  1. Click Save and deploy and wait for your website to be built!
    2. \n
\n

Cloudflare Pages

\n

It's very easy to publish your squido website for FREE using Cloudflare pages. Free SSL, custom domain, global CDN and more and just super simple to setup.

\n
    \n
  1. Login here
    2. \n
  2. Select Create new project
    3. \n
  3. Link your Github account and select your repository, then Begin setup
    4. \n
  4. Setup like:
    5. \n
\n

\"Cloudflare

\n
    \n
  1. Click Save and deploy
    2. \n
  2. Wait for the build to complete
    3. \n
  3. You can then setup Custom domains and you are done
    4. \n
\n

Digitalocean Apps

\n

Digitalocean Apps makes hosting your static HTML squido website for FREE just so bloody easy. Digitalocean Apps offers free SSL, custom domain, global CDN and more.

\n
    \n
  1. Login here
    2. \n
  2. Select Github as source and choose your squido Repository:
    3. \n
\n

\"Digitalocean

\n
    \n
  1. Hit Next
    2. \n
  2. Setup like:
    3. \n
\n

\"Digitalocean

\n
    \n
  1. Hit Next.
    2. \n
  2. Name your app then hit Next once more
    3. \n
  3. Select the plan. Choose Starter for FREE hosting
    4. \n
  4. Hit Launch Starter App
    5. \n
  5. Wait for your app to build. Watch the logs by clicking the View logs button
    6. \n
  6. Once your build is complete you can select Settings and configure your domain and more
    7. \n
\n

You are done. Enjoy your super fast hosting on the awesome Digitalocean platform!

\n

Azure Static Web Apps

\n

Publishing your squido website to Azure Static Web Apps is very easy and low cost.

\n
    \n
  1. Visit https://portal.azure.com, login and create a free Static Web App.
    2. \n
  2. To use Azure DevOps instead of a Github repo, select Other under Deployment details.
    3. \n
  3. Once the resource is provisioned, from the Static Web App Overview page, click Manage Deployment Token. Copy this token somewhere safe. It will be used later.
    4. \n
\n

\"image\"

\n
    \n
  1. Visit https://devops.azure.com, login and create a New Project
    2. \n
  2. Click Repos and clone the Azure repo to your local machine. Either move your existing squido site into this local repo, or create a new squido site. Commit and push code to this Azure DevOps repo
    3. \n
  3. Click Pipelines and create a new Pipeline for the project. Select Starter Pipeline and paste in the yaml template below
    4. \n
\n
trigger:\n  - main\npool:\n  vmImage: ubuntu-latest\nvariables:\n- name: NODE_ENV\n  value: production \nsteps:\n  - checkout: self\n    submodules: true\n  - task: AzureStaticWebApp@0\n    inputs:\n      app_location: '/'\n      output_location: '/build'\n      azure_static_web_apps_api_token: $(deployment_token)\n
\n
    \n
  1. Click Variables then New Variable
    2. \n
  2. Name the variable deployment_token and paste in the Deployment Token from Step 1c. above
    3. \n
  3. Save and run the Pipeline
    4. \n
  4. Visit the URL shown in Static Web Apps in Azure Portal
    5. \n
\n", "url": "https://squido-docs.markmoffat.com/deployment-and-hosting/", "title": "Deployment and hosting", "summary": "Getting started with deploying and hosting your squido website. Deployment guides using Netlify, Github Pages, AWS Amplify, Cloudflare Pages, Digitalocean app and more", "date_modified": "2021-02-28T01:52:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/admin-editor/", "content_html": "

The squido admin panel is accessible after running the serve.

\n

Running serve:

\n
$ squido serve -b -c -w\n
\n

Open the following in a browser: http://localhost:4965/squido

\n

You should see:

\n

\"squido

\n

Here you can create, edit and delete any posts for you website. Once you have completed you simply need to deploy or Git commit and push to your repo.

\n", "url": "https://squido-docs.markmoffat.com/admin-editor/", "title": "Admin editor", "summary": "squido admin allows you to edit your website content straight from your browser. You can create, edit and delete posts without using a text editor.", "date_modified": "2021-02-27T01:52:00.000Z" }, { "id": "https://squido-docs.markmoffat.com/post-build-tasks/", "content_html": "

Post build tasks are tasks which run after the website is built. You can configure zipping up your website, automatic deployment etc to make deploying your website faster. See configuration for information on configuring a task.

\n

Zip

\n

The zip postBuild task simply zips all the files in your /build directory into a file called build.zip located here: /build/build.zip. You can then send/upload this file to your website host, FTP it or back it up.

\n

An example config.js configuration is below. There are no options for this task.

\n
production: {\n  name: 'squido docs',\n  description: 'Squido documentation - A dead simple static website generator',\n  ...\n  postBuild: [\n    {\n        name: 'zip',\n        options: {}\n    }\n  ]\n  ...\n}\n
\n

Netlify

\n

The netlify postBuild deploys your website to Netlify without the use of Git. This task requires the zip task to also be configured before this task (see below config) as this task will upload the zip file containing your website direct to Netlify using their file upload API.

\n

An example netlify task configuration is below. You can see the zip task is configured first:

\n
production: {\n  name: 'squido docs',\n  description: 'Squido documentation - A dead simple static website generator',\n  ...\n  postBuild: [\n    {\n        name: 'zip',\n        options: {}\n    },\n    {\n      name: 'netlify',\n      options: {\n        siteName: 'squido test website'\n        apiToken: 'my-netlify-api-token'\n      }\n    }\n  ]\n  ...\n}\n
\n

To use this task you will need to obtain your apiToken from Netlify by:

\n
    \n
  1. Logging into Netlify here https://app.netlify.com/user/applications
    2. \n
  2. Under Personal access tokens, click New access token
    3. \n
  3. Set a name of your token which you will remember.
    4. \n
  4. Copy the token and add to your config.js file under apiToken
    5. \n
\n

After you run:

\n
$ squido build -c\n
\n

The build files of your website will first be added to a zip file, then that file is uploaded to Netlify to be built and served. You can then view your Netlify websites under the Sites tab and can control your custom domain and other settings.

\n", "url": "https://squido-docs.markmoffat.com/post-build-tasks/", "title": "Post build tasks", "summary": "Getting started with the squido post build tasks", "date_modified": "2021-02-26T01:52:00.000Z" } ] }