DEV Community: Richard Guay

Sending Emails from Command Line using EmailIt

Richard Guay — Thu, 27 Jul 2023 05:42:31 +0000

I just recently released an update to the EmailIt that includes many great new features:

A TUI application for sending emails from the command line
The body text of all emails are processed through the builtin Handlebars parser to expand macros.
Removed Script Terminal for Scriptline.
Added many new API endpoints to use to control EmailIt.
Many great bug fixes and updates overall.

But, Let's just look at the commandline EmailIt TUI.

TUI

The word TUI comes from Terminal User Interface. It is basically creating a graphical user interface in a terminal. The EmailIt program is both a graphic interface and a command line TUI. First download the program from the GitHub repo: https://github.com/raguay/EmailIt. Unzip it and move it to the /Applications folder.

In order to use the program from the command line, you need to make an alias to the programs executable file for the macOS:

alias em=/Applications/EmailIt.app/Contents/MacOS/EmailIt

With the above line in your .bashrc or .zshrc file (you will have to make a similar line for other shells), you can run the EmailIt program from any directory. The different command line options are shown with the basic -h or --help flag or the help or h command:

> em help
NAME:
   EmailIt - A program for sending emails, working with text, and scripts.

USAGE:
   EmailIt [global options] command [command options] [arguments...]

VERSION:
   v2.1.0

AUTHOR:
   Richard Guay <raguay@customct.com>

COMMANDS:
   mkemail, me     Create an email using a TUI
   notes, n        Open the notes.
   emailit, e      Open the EmailIt email sending application.
   scriptline, sl  Open the ScriptLine application.
   sendemail, se   Send the email directly. No GUI or TUI.
   help, h         Shows a list of commands or help for one command

GLOBAL OPTIONS:
   -a value       Address to send an email
   -s value       Subject for the email
   -b value       Body of the email
   --help, -h     show help
   --version, -v  print the version

COPYRIGHT:
   (c) 2022 Richard Guay

The -a flag will take the value and put it for the address to which to email. The -s flage will take the value and place it in the Subject field of the email. The -b flag will take the value and place it in the body of the email. The mkemail or me command will then open the TUI for creating the email. The sendemail or se command will take the command line information and send the email directly without using the TUI. The notes or n command will open EmailIt to the notes screen. The scriptline or 'sl' command will open the Scriptline screen. The emailit or em command will open the EmailIt screen.

The TUI looks like this:

If you have the Default account setup in EmailIt, it will then send your email to that account. The resulting email from the gif video would look like this:

Your all set to do emails from the commandline!

Building Bulletin Board

Richard Guay — Sat, 10 Dec 2022 11:53:00 +0000

My Problem

In my job, I often need some information to stay on top of eveything. I’ve tried may types of stickit notes and other programs, but they all seem to be too large and not easy to script. I also need information from several systems in my home network. Therefore, I created the original BulletinBoard in NW.js that works quite well, but now I need to make it smaller. Also, the old code is kind of hacky. NW.js is a great way to build applications using HTML, CSS, and JavaScript. Since it is so easy to use, I’ve used it to create first pass demo applications. The problem with it is that it’s a full Chrome web browser. For a small application, that is just too much wasted memory. Therefore, I’m doing a full redesign in Wails to bring down it’s footprint.

Wails

Wails is a go language program to create HTML, CSS, and JavaScript applications with a go language backend. It creates really small builds because it uses a system HTML browser that is minimal in size (and therefore, minimal APIs). This allows the program to work on Windows, Linux, and macOS and still have a very small footprint. I’ve converted several of my programs to Wails: Modal File Manager, EmailIt, and ScriptBar.

In order to get the same functionality with the original BulletinBoard program, I need to have a full web server built in. The orginal version allowed me to do just that with the Node.js backend. Now, I need to figure out how to do the same with go lang and still work with Wails.

Wails already runs a web server backend (I suspect it is web sockets based) to work with the frontend of the program. Since I can’t piggy back on it, I have to have a separate web server backend. This is necessary since the frontend JavaScript doesn’t support doing a server.

The question becomes: Can you run a separate web server on the same go backend?

Things Wails Currently Doesn’t Do

While writing this article, Wails 2 is still in development and doesn’t have every feature needed for this application. For instance, it can’t run with the Dock icon not showing and a menubar icon only. Those are still in the works. But, it can control the hiding and showing of the program. It can also make the window always on top. Therefore, most of the functionality is ready for this application.

Bulletin Board Design

The go language has several backends for running a web server. I’ve decided to use the gin backend since it is real easy to use and seems to be the most popular one. I’ve only done one project in go before, but it is an easy language to pickup.

The design is based on an API backend that receives GET requests on the route /api/messages/:message with the :message is the message to display. The same message is in the body in JSON format as:

{
  msg: message
}

Where message is the same text in the web address. It's done this way because of the original design was first based on the web address only, but longer messages needed the body. It is a hack, but it worked and there isn’t time to change everything! Also, a GET request is easy to implement in scripting languages (like using wget or curl command line programs).

BulletinBoard Communications - Made with OneModel

The backend receives this request and uses signals to pass it to the frontend. Wails has a great event based message sending framework. The frontend is done using Svelte. The original was plain JavaScript and HTML and not too pretty (Okay, it was a quick hack). Now, I’m using a nice framework to build a modular system that is easy to expand.

The original design allowed for dialogs to send back information as well. For this project, I’m just doing the messaging system to see if I can get it to work using Wails and the go language server.

Let’s Get Started

To get started, you need to install nodejs with npm, go language, and Wails 2. I’m using version 43 of Wails 2 in this article.

Create a directory for your project and run the following command line to initialize a Wails project with Svelte:

wails -n “BulletinBoard” -d . -t “svelte"

This will create a Svelte frontend Wails project with normal JavaScript. If you want to use TypeScript, use the template “svelte-ts”.

The first thing is to setup the main.go file as shown below:

package main

import (
    "embed"

    "github.com/wailsapp/wails/v2"
    "github.com/wailsapp/wails/v2/pkg/options"
    "github.com/wailsapp/wails/v2/pkg/options/mac"
)

//go:embed frontend/dist
var assets embed.FS

//go:embed build/appicon.png
var icon []byte

func main() {
    // Create an instance of the app structure
    app := NewApp()

    // Create application with options
    err := wails.Run(&options.App{
        Title:             "BulletinBoard",
        Width:             100,
        Height:            60,
        Assets:            assets,
        BackgroundColour:  &options.RGBA{R: 27, G: 38, B: 54, A: 0},
        DisableResize:     true,
        Fullscreen:        false,
        Frameless:         false,
        StartHidden:       true,
        AlwaysOnTop:       true,
        HideWindowOnClose: true,
        OnStartup:         app.startup,
        OnDomReady:        app.domReady,
        OnShutdown:        app.shutdown,
        Bind: []interface{}{
            app,
        },
        Mac: &mac.Options{
            TitleBar:             mac.TitleBarHiddenInset(),
            Appearance:           mac.NSAppearanceNameDarkAqua,
            WebviewIsTransparent: true,
            WindowIsTranslucent:  true,
            About: &mac.AboutInfo{
                Title:   "BulletinBoard",
                Message: "© 2022 Richard Guay <raguay@customct.com>",
                Icon:    icon,
            },
        },
    })

    if err != nil {
        println("Error:", err.Error())
    }
}

This setups a typical program with transparent backgrounds and hidden on startup. The OnStartup entry is set to app.startup which is where we will launch our server. Launching the server at this location will have all the custom code in one place and allows the Wails server for the frontend to be initialized first.

Next, we need to create our application logic in the app.go file. Add the following information:

package main

import (
    "context"
    "github.com/gin-gonic/gin”    // webserver framework
    rt "github.com/wailsapp/wails/v2/pkg/runtime”. // Wails runtime
    "net/http"
    "net/url"
)

// App struct
type App struct {
    ctx context.Context
}

// NewApp creates a new App application struct
func NewApp() *App {
    return &App{}
}

func (a *App) domReady(ctx context.Context) {

}

func (a *App) shutdown(ctx context.Context) {

}

// startup is called when the app starts. The context is saved
// so we can call the runtime methods
func (a *App) startup(ctx context.Context) {
    a.ctx = ctx

    //
    // We need to start the backend and setup the signaling.
    //
    go backend(ctx)
}

This is mostly setup code except for the startup function. The ctx variable is the context for the whole application and is needed for the server to run. It is passed to the server using the line:

  go backend(ctx)

The go at the front of the backend function name tells go to run the server as a go coroutine. This runs on a separate thread that doesn’t interfere with the other frontend code. This allows the server to run without bothering anything else and makes this project functional.

Then add the following to the bottom of the app.go file:

type Msg struct {
    Message string `json:"msg" xml:"user"  binding:"required"`
}

func backend(ctx context.Context) {
    //
    // This will have the web server backend for BulletinBoard.
    //
    r := gin.Default()
    r.Use(gin.Recovery())

    //
    // Define the message route. The message is given on the URI string and in the body.
    //
    r.GET("/api/message/:message", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "msg": "okay",
        })
        var json Msg
        if err := c.ShouldBindJSON(&json); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        message := c.Param("message")
        messageBody := json.Message
        if messageBody != message {
            message = messageBody
        }

        message, err := url.QueryUnescape(message)
        if err != nil {
            // An error in decoding.
            message = ""
        }

        //
        // Send it to the frontend.
        //
        rt.EventsEmit(ctx, "message", message)
    })

    //
    // Run the server.
    //
    r.Run(":9697")
}

This is a basic setup for a single route in the gin web server framework. It is very basic right now, but very functional. I need to add middleware that does security checking to make the program more secure. But, we just want to demostrate that this approach is possible.

The function for the route gets the message from the URI and the body JSON structure. It then decodes it from URI encoding and checks to see if they are the same. If so, just send on the one from the URL. Otherwise, it sends the one from the body.

The interesting part is the next line that uses Wails runtime rt.EventsEmit() function to tell the frontend that we have a new message to display. The event has the name “message” that the frontend will receive and setup for displaying a message. This is important for expanding for other types in the future.

In the frontend/src/main.js file, add this information:

import BulletinBoard from './BulletinBoard.svelte'

const app = new BulletinBoard({
  target: document.body
})

export default BulletinBoard

This is simple boilerplate code for starting a Svelte application. The BulletinBoard.svelte file is the main program.

Now for the main program. Create the BulletinBoard.svelte file with the frontend/src directory with the following code:

<script>
  import { onMount, afterUpdate } from "svelte";
  import Message from "./components/Message.svelte";
  import { state } from "./stores/state.js";
  import { theme } from "./stores/theme.js";
  import { message } from "./stores/message.js";
  import * as rt from "../wailsjs/runtime/runtime.js"; // the runtime for Wails2

  let containerDOM = null;
  let minWidth = 300;
  let minHeight = 60;

  onMount(() => {
    $state = "nothing";
    getTheme();

    //
    // Set a function to run when a event (signal) is sent from the webserver.
    //
    rt.EventsOn("message", (msg) => {
      if (msg.trim().length !== 0) {
        //
        // Set the message state and save the message in the store.
        //
        $state = "message";
        $message = msg;

        //
        // Show window in case it's off.
        //
        rt.WindowShow();
      } else {
        //
        // An empty message send by having just a space turns off the BulletinBoard.
        //
        rt.WindowHide();
      }
    });
  });

  afterUpdate(() => {
    //
    // The nothing state should force a window hiding.
    //
    if($state === "nothing") {
      rt.WindowHide();
    }

    //
    // Figure out the width and height of the new canvas.
    //
    if (containerDOM !== null) {
        let width = minWidth;
        let height = minHeight;
        if (height < containerDOM.clientHeight) height = containerDOM.clientHeight;
        if (width < containerDOM.clientWidth) width = containerDOM.clientWidth;
      rt.WindowSetSize(width, height);
    }
  });

  function getTheme(callback) {
    //
    // This would read the theme from a file. It currently just sets a typical theme.
    // I love the Dracula color theme.
    //
    $theme = {
      font: "Fira Code, Menlo",
      fontSize: "12pt",
      textAreaColor: "#454158",
      backgroundColor: "#22212C",
      textColor: "#80ffea",
      borderColor: "#1B1A23",
      Cyan: "#80FFEA",
      Green: "#8AFF80",
      Orange: "#FFCA80",
      Pink: "#FF80BF",
      Purple: "#9580FF",
      Red: "#FF9580",
      Yellow: "#FFFF80",
    };
  }
</script>

<div
  id=“closure"
  bind:this={containerDOM}
  style="background-color: {$theme.backgroundColor}; color:    
  {$theme.textColor}; font-family: {$theme.font}; font-size: 
  {$theme.fontSize};"
>
  <div id="header" data-wails-drag>
    <h3>Bulletin Board</h3>
  </div>
  <div id="main">
    {#if $state === "message"}
      <Message />
    {/if}
  </div>
</div>

<style>
  :global(body) {
    margin: 0px;
    padding: 0px;
    overflow: hidden;
    border: transparent solid 1px;
    border-radius: 10px;
    background-color: transparent;
  }

  #closure {
    display: flex;
    flex-direction: column;
    margin: 0px;
    padding: 0px;
    border-radius: 10px;
    overflow: hidden;
  }

  #header {
    height: 20px;
    margin: 0px;
    padding: 5px;
    -webkit-user-select: none;
    user-select: none;
    cursor: default;
  }

  #main {
    display: flex;
    flex-direction: column;
    margin: 0px 0px 0px 20px;
    padding: 0px;
    min-width: 100px;
  }

  h3 {
    text-align: center;
    margin: 0px;
    padding: 0px;
    cursor: default;
    font-size: 1 em;
  }
</style>

The onMount function tells Svelte compiler to run the code while mounting this component. This code initializes the theme stored in the $theme state store. The function then sets up the event receiver to receive “message” events using the rt.EventsOn function. When it gets a message, it sets the $message store variable to it and sets the $state store variable to “message”. This tells the HTML code to show the Message component and show the window using rt.ShowWindow().

The bind:this={containerDOM} will put the DOM node into the variable containerDOM. This can then be queried to find out information about the div node that contains the message.

The next interesting bit of code is in the afterUpdate function call. This sets a function to call after all components are setup and visible. In this one, it first sets the window to hidden if the state equals “nothing”. Therefore, it creates an easy way to hide the window from anywhere simply by setting the state variable. Secondly, it uses the containerDOM variable to adjust the window size based on the application div size. It also keeps it from getting too small.

The rest of the code simply sets up the HTML and CSS for creating the main window. Now, we can go on to the Message component.

Now create the frontend/src/components/ directory and create the Message.svelte file with this information:

<script>
  import { message } from "../stores/message.js";
</script>

<div id="message">
  <span>{$message}</span>
</div>

<style>
  #message {
    display: flex;
    flex-direction: column;
    margin: 0px;
    padding: 10px;
  }
</style>

This is an easy component since it just displays a message. You might be thinking that I’m showing unsantitize user given information in the HTML with the line {$message}. The brackets tell Svelte to get the result of the JavaScript expression, santitize it, and display it. Here, we are displaying the information in the $message store variable. Since Svelte does the sanitizing, I don’t have to worry about it.

This looks very trivial to make a full component, but this is modular design. I just add more components for doing different types of displaying. The other display types will have much more code in them.

The remaining parts are the different Svelte stores used in this project. The different stores are in the directory frontend/src/stores and can seen in the GitHub BulletinBoard project page. This is an ongoing project and this repro reflects that with more functionality being written each week….well, when I have time for them.

The application is built with the command line:

wails build --platform "darwin/universal”

Which creates a macOS universal binary and bundles it all up in an application bundle called BulletinBoard.app in the build/bin directory.

If you aren’t on a macOS system, then just use:

wails build

When the application is ran, a requester dialog asking if you want it to allow the program to accept incoming network connections will appear (macOS only). Simply allow it and the program is running. But wait, nothing shows up. That is because the application was started in the hidden state. In order for the program to become visible, it has to receive a message request.

In order to send messages to it, you have to create a message sending program. This is done with a small ruby script:

#!/usr/bin/env ruby
require 'net/http'
require 'json'

def uri_encode(str)
  str.gsub(URI::UNSAFE) do |match|
    match.each_byte.map { |c| sprintf('%%%02X', c.ord) }.join
  end
end
if ARGV[0] == '-' then
  message = ''
else
  message = uri_encode(ARGV[0])
end

uri = URI("http://localhost:9697/api/message/#{message}")
http = Net::HTTP.new(uri.host, uri.port)
req = Net::HTTP::Get.new(uri.path, 'Content-Type' => 'application/json')
req.body = {msg: "#{message}"}.to_json
res = http.request(req)
puts "response #{res.body}”

If you put this in a file named ‘sendmsg’ and set it to executable, you can type the following command line:

sendmsg “hello”

The BulletinBoard application will show up like this:

Conclusion

This tutorial just proved that there can be multiple web servers inside of a single Wails application thanks to the go language's use of coroutines. This works great and now I can finish the other functions. I want to be able to display script supplied dialogs to the user and return JSON data structure with the results.

If your interested in keeping up with this project or simply want to download the source yourself, you can find it on the GitHub page for BulletinBoard. It already doesn’t look like it does here since it is an ongoing project. It has a discussion board for asking questions or just to comment on it.

On to the next steps!

Note: The article picture is from Envato Elements.

EmailIt First Release!

Richard Guay — Wed, 10 Aug 2022 07:02:31 +0000

This is just to let everyone know that I just released the first version of the EmailIt program. The documentation isn't all there, but the program works. I use it everyday on my computer. It is built as a macOS universal build. It is built using Wails, and Svelte.

It’s a handy little markdown based email sending only program with nine notepads, scripts to manipulate the text, and templates. It also has a script terminal with minimal commands, a bundled Node-Red server, and the ScriptBar program.

Give it a try and let me know how you like it in the discussions.

First Release of the New Modal File Manager

Richard Guay — Thu, 31 Mar 2022 05:40:21 +0000

I’ve just released the first version of the new Modal File Manager for the macOS. It is built using Wails 2 and Svelte. It is a complete universal application that should work on Intel and M1 Macs. I’ve been develping and using it on my M1 MacBook Pro for several weeks now. I use it as my main file manager everyday.

If you have a problem, please leave an issue so that I can track it down and fix it. I haven’t built it on a Linux or Windows system. Therefore, I’m not sure how well it will do there.

You can read the annoucement here and download the program here.

Currently, the only documentation is the GitHub README.md file. You can read it here. I’ll be working on better documentation soon.

Modal File Manager: Update and Extensions

Richard Guay — Thu, 01 Jul 2021 04:34:19 +0000

I recently wrote an update to my Modal File Manager project called Modal File Manager: Update and Extensions. It goes into many new features that I've added to the Modal File Manager, how to install the macOS version that I bundled for downloading, and all the themes and extensions that I've created for the Modal File Manager.

I hope you enjoy this fun little project and decide to help me in the journey to create a very powerful, dual file pane file manager together!

My Latest Side Project: Modal File Manager

Richard Guay — Mon, 12 Apr 2021 04:19:54 +0000

On my blog site, I just added a post about my latest side project: Modal File Manager. It is a two pane file manager with a twist: it uses state based key mapping just like Vim!

It is a new project that is currently in Alpha stage. You can download from my GitHub account and play with it. It is built using Svelte, Nw.js, and mask script running.

I’m looking for people to help with the project. It is an open source project, so jump right in. At least let me know what you think and any suggestions you might have.

Controling your Computer from a Phone

Richard Guay — Fri, 15 Jan 2021 10:47:17 +0000

A little while ago, someone asked what can be done with a older tablet or phone. I mentioned that you could control your computer with one. I’ve been doing it for a while with my Huawei phone or my Kindle Fire using a local web server on my computer. The person, I don’t remember who or on what forum we were talking, asked me to share it. Well, it was embedded deeply in another project. But, I decided to extract it and make it available.

Well, it is done and available on my GitHub account. Feel free to download, expand upon it, and just have fun. If you add something interesting or just neat, send a pull request. It’s current state is far from ideal. You have to change the code to configure the buttons right now, but it gives a good idea of what you can do.

Word of Caution: it doesn’t have great security right now. I will be looking into adding that soon. In the meantime, I recommend only using it in a trusted and secure local network.

File Organization

At the top level, there are three things: the server directory, the UI directory, and a maskfile.md file for using mask. Mask is a great tool for running scripts on your project. I use it all the time.

The server directory has all the code for running the local Express.js server. You should not need to edit this file unless you are adding new features to the backend (like security).

The UI directory contains most of the code. Here, you can edit the tiles displayed and the actions they perform. This code is written in Svelte for speed and small foot print. Svelte is a great framework for writing Single Page Applications (SPA).

The UI/src directory contains all the files for creating the user interface. The UI/src/main.js file contains all non-Svelte code. Every other file is written in Svelte and has the .svelte extension.

The UI/src/main.js file contains the structures you will want to change to add more buttons and change the theming.

Adding/Removing Buttons

The heart of the program is the scriptList structure. This is a two dimensional array of objects that define a tile (the button you press to evoke a program or script). The row of tiles is an array of those objects. So, to add a new row or remove a row, add or remove an array.

The tile object is of the following format:

{
  name: "Open fman",
  description: "Open a copy of the fman program.",
  script: "/Applications/fman.app/Contents/SharedSupport/bin/fman",
  args: ['&'],
  color: "lightgreen",
  textColor: "darkgreen",
  height: "70px",
  width: "30%"
}

The name is the name of the tile, description describes what action the tile performs, program is the program or script to run, args is an array of command line arguments used to run the command, color is the background color for the tile, textColor is the color for the text in the tile, height is the height of the tile, and width is the width of the tile. When describing the height or width, you can use percentages or fixed numbers in pixel, rem, or any other CSS measurement standard. When specifying the height, don’t use percentage as that will be the percentage of the row that it is on.

When you run a program, it will use the environment that the server is launched. If you launch the server in the root environment, then your programs will have the privileges and environment variables of that environment. Therefore, be very careful! I only run it in my own login. But, if it automatically launches in a startup script, then it will have the environment of the startup script that doesn’t always match your normal environment. Alfred users run into this issue often.

The only other interesting structure is the styles structure that controls the look of the background of the web page. Only two things can be currently configured: backgroundColor and textColor. These are very self explanatory.

Running the Server

While in the top directory where the mask file.md file is, run the following command:

mask LaunchServer

This only works if you have the mask taskrunner on your computer. This command will compile the UI code and launch the Express.js server. Now open a web browser to http://localhost:3000 and you will see the main page.

In the upper right corner is a button labeled Show QR Code. By clicking this button, a QR code will be displayed. Scan that code with your mobile device and open the given web address in your browser. You will see the same page without the Show QR Code button. You are now setup to launch programs on your computer from your phone or tablet!

By clicking the QR code on your computer, it will go away. Same with clicking the button again.

Conclusion

Now that you know about this software, play with it and let me know how you use it. If you add something useful, send a pull request. Above all, have fun!

A Corvid-19 Widget for the Plash Server

Richard Guay — Fri, 20 Mar 2020 15:08:55 +0000

Well, with all the noise about the Corvid-19 virus, I decided to make a widget that works with my Plash server project.

I have a full tutorial series on my personal blog site. My latest tutorial is a Corvid-19 widget and a Text widget. This widget will show the current infection rate for any country you are interestd in. On my background, it shows for Thailand (where I live) and the USA (where I’m from).

This series assumes you know very little about Svelte. I am trying to use it as a way to get more people interested in Svelte framework and know how to use if for their needs. I think it makes a great playground to learn Svelte.

I would love to see your comments on this series. All code is located on my GitHub repository for the PlashServer. Fork it, expand it, and send me some pull requests. It would be a lot of fun to have a community contributing to this project.

Adding an Exchange Rate Display to the PlashServer

Richard Guay — Mon, 02 Mar 2020 09:08:28 +0000

I’m one of those people that love to control what’s on the background of my computer. I’ve used many widget tools to perform these tasks, but they all left me as under developed, hacky at times, and not as easy to use as I would like. That’s most likely because I never took the time to really get into their code structures. But, when you create your own thing, then you know it very well.

When the Plash program came out for the macOS, I jump right onto it. It allows you to put any website, whether a local file system one or one served on the net, as your background. That directly inspired me to create a Svelte based background webpage for Plash.

I have a full tutorial series on my personal blog site. The first tutorial takes you through the building of the basic framework and getting everything running with Plash. The initial widgets are a circular time display with the actual time under it.

My latest tutorial is an Exchange Rate widget. This widget will show the current exchange rate for whatever currency your interested in seeing. Since it’s a widget, you can add it onto your screen as many times as you like. This tutorial really shows how to make use of promises in the Svelte framework.

Using the Svelte GitHub Website Template

Richard Guay — Tue, 31 Dec 2019 09:20:00 +0000

Originally posted on 2019-12-06 at Custom Computer Tools.

Many want to run a simple blog or a small website without spending a whole lot of money. They often believe they have to sacrifice speed and flexibility to get it going cheap enough for them. But, the truth is, you can create a website for free!

This tutorial will show you how you can create your own website with simple markdown files and a GitHub Pages account. You are going to build a site using the Svelte framework and the Svelte GitHub Website Template.

This template creates everything you need to get a working website going on your computer, and then putting it on the web using GitHub. Since it is basically a flat file system website, you will not need to install a full web server stack. The Svelte installation supplies a Node.js based development server with live
reload to view your site as you are building it.

This template has partials for taking pieces of code and placing it in your site where ever you need it in the markdown pages. It also has a macro expansion ability based on Handlebars with some added helpers that I've designed. Since your pages are created using markdown, it would be good to become familiar with how it works.

Tools you will need

You will need to have Node.js, git, Mask task runner, a web browser, and a text editor. You don't have to have Mask, but I do highly recommend using it. I'm personally using the Oni 2 editor for writing and programming, but you can use any editor that you are used to using.

I'm working on a macOS system, but any computer system that can run the above tools should work fine. If you are on windows, you might need to use the Maid task runner instead. Mask is a Rust program and hasn't been tested on Windows much, but Maid is a Node.js program and should run anywhere that Node.js runs. I will show you all the steps for making your own scripts if you don't want to use a script runner.

Downloading the Template and Running the Development Server

In a terminal program, like Kitty, go to the directory you would like your website directory. In that directory, run the following command line:


npx degit raguay/SvelteGithubSiteTemplate <project name>
cd <project name>

The <project name> is the name you give your website. Therefore, if you want the directory for your website to be called MyBlog, then use MyBlog instead of <project name>. The above command lines become:

npx degit raguay/SvelteGithubSiteTemplate MyBlog
cd MyBlog

Now you are in the website directory. The website directory should have a directory/file structure as shown (tree is a unix command for showing the current directory down in a graphical tree structure):

 $ tree
├── LICENSE
├── README.md
├── launch
│  ├── README.md
│  ├── css
│  │  └── bundle.css
│  ├── index.html
│  └── js
│      └── bundle.js
├── maskfile.md
├── package.json
├── public
│  ├── CNAME
│  ├── bundle.css
│  ├── bundle.css.map
│  ├── bundle.js
│  ├── bundle.js.map
│  ├── index.html
│  └── site
│      ├── 404.md
│      ├── blog
│      │  ├── index.md
│      │  └── my-first-post.md
│      └── parts
│          └── test.html
├── rollup.config.js
└── src
    ├── WebSite.svelte
    ├── components
    │  ├── About.svexy
    │  ├── BlogPosts.svelte
    │  ├── Footer.svelte
    │  ├── Index.svexy
    │  ├── Logo.svelte
    │  ├── NavBar.svelte
    │  ├── Page.svelte
    │  ├── Sidebar.svelte
    │  └── Twitter.svelte
    ├── main.js
    └── store
        └── infoStore.js

10 directories, 31 files

Next, run the npm command to install the node.js libraries needed to work on this website:

npm install

This takes a while if you've never installed some of the node.js packages. On my system, it took 44 seconds. Once done, you can now run the development server and see what your website looks like:

npm run dev

When you see the waiting for changes... in the terminal, your site has been compiled and is running on a local server. You can open a browser and view your site at http://localhost:5000. The local server puts code into your site to auto refresh your browser whenever you change any file in the src directory. When you do, it will recompile the code and force a refresh on your browser.

The Two Types of Pages

There are two types of pages in this template: a Svelte component and markdown files. In the current site, the About.svexy and Index.svexy components are for the main site index page (ie: the front page of your website), and the about page. These can be any valid Svelte component. In this template, they are markdown files that use Mdsvex. Mdsvex is a markdown type file that is compiled into a normal Svelte component and added to the bundle.js file. Therefore, these pages are always loaded into the browser of the person looking at your site. You should keep these types of pages as minimal as possible to keep your load time as fast as possible.

To see the minimal code for one of these pages, look at the About.svexy file in the src/components directory:

\`\`\`js exec
  import { fade } from 'svelte/transition';
  import { onMount } from 'svelte';
  import { info } from '../store/infoStore.js';

  onMount(() => {
    //
    // Subscribe to the information store to get the site information.
    //
    const unsubscribeInfo = info.subscribe((value) => {
    });

    return () => { unsubscribeInfo(); };
  });


\`\`\`

\`\`\`css style
  .box {
    width: 100%;
    margin: auto;
    padding: 10px;
    margin-top: 10px;
    margin-bottom: 10px;
  }
\`\`\`

<div class="box" style="border: {$info.styles.borderSize} solid {$info.styles.borderColor}; 
                        border-radius: {$info.styles.borderRadius}; 
                        background-color: {$info.styles.divColor};
                        background-image: {$info.styles.divBackgroundPicture};
                        color: {$info.styles.textColor};" in:fade="{{duration: 500}}">

## About Us

This is a markdown file with information about you. Change as you see fit.

The `div` setup the proper styling for the markdown and controls the animation of it on the site. Therefore, leave the div information as it is and just change the markdown in between.

</div>

There are two code blocks that the Mdsevx package will include in the module as JavaScript and CSS. The js exec code block is added as JavaScript to the created Svelte code and the css style is added to the Svelte CSS block. Note: The extra back slashes are for allowing this website editor to show the back ticks. They are not in the actual file. Anyone know a better way to do this?

The style block sets the styling for the div element to show it properly on the site. The JavaScript section loads the Svelte code needed to get the styling information from the info store and the fade directive for the div block. Just add the markdown you want in the area between the <div> and </div> elements.

If you want to include other components, just load them in the JavaScript section just like any other Svelte component and put the markup in the place you want it to be in the markdown. Just like standard markdown, you can mix in HTML code as needed. This makes for a very versatile page creation. Anything you want to do can be done in these pages!

The other type of page is the markdown pages. They are any page under the site directory in the public and launch folders. Any page request that doesn't match a Svelte component in the router is expected to have a corresponding markdown file. For example, the page localhost:5000/blog/index will send the file public/site/blog/index.md to the user to see.

If a file request is sent that doesn't match a component or a markdown file in the system, then the public/site/404.md file will be processed and sent to the viewer. This file is actually preloaded when the partials are preloaded. You will see how to load partials in the next section.

These markdown files are limited to plain markdown, any registered Handlebars helpers, and everything that is in the YAML header is available as a Handlebar helper. Here are a list of helpers I've added to the template:

Helper	Description
`{{save <name> <text>}}`	This command creates a helper named `<name>` with the expanding text of `<text>`. It also places the given `<text>` at the point of definition. This allows you to create text snippets on the fly inside the template. Very handy.
`{{date <format>}}`	This will format the current date and time as per the format string given.
`{{cdate <date/time> <format>}}`	This takes the date/time string and formats it according to the format given.
`{{last <weeks> <dow> <fmat>}}`	This will go back in time to `<weeks>` ago and give the date for the particular `<dow>` (Day Of Week) in the `<fmat>` format.
`{{next <weeks> <dow> <fmat>}}`	This will go forward in time to `<weeks>` ahead and give the date for the particular `<dow>` (Day Of Week) in the `<fmat>` format.
`{{cDateMDY}}`	gives the current date in Month Day, 4-digit year format
`{{cDateDMY}}`	gives the current date in Day Month 4-digit Year format
`{{cDateDOWDMY}}`	gives the current date in Day of Week, Day Month 4-digit year format
`{{cDateDOWMDY}}`	gives the current date in Day of Week Month Day, 4-digit year format
`{{cDay}}`	gives the current date in Day format
`{{cMonth}}`	gives the current date in Month format
`{{cYear}}`	gives the current date in 4-digit year format
`{{cMonthShort}}`	gives the current date in Short Month name format
`{{cYearShort}}`	gives the current date in 2-digit year format
`{{cDOW}}`	gives the current date in Day of Week format
`{{cMDthYShort}}`	gives the current date in Month day 2-digit year format
`{{cMDthY}}`	gives the current date in Month Day 4-digit year format
`{{cHMSampm}}`	gives the current date in h:mm:ss a format
`{{cHMampm}}`	gives the current date in h:mm a format
`{{cHMS24}}`	gives the current date in H:mm:ss 24 hour format
`{{cHM24}}`	gives the current date in H:mm 24 hour format

The time formatting is done using the Moment.js library. Please refer to that website for the details on how to create the format string.

These are the same helpers available in my Alfred Workflow Quiver and Template. Those workflows are using the same base code I'm using with the Svelte GitHub Website Template project. Yes, I reuse stuff that I like! Please refer to the Handlebars documentation for any built in helpers.

If you want to add your own helpers, then add them to the src/components/Pages.svelte file. All helpers that are not time sensitive should be placed in the onMount() function with the ones I have there. The helpers that are time sensitive should be placed in the processData() function. For example, the {{save <name> <text>}} helper is in the onMount() function since it is saving data on the page for use further in the page and isn't a time based function.

Changing Site Information

All basic site information is kept in a Svelte store. Any component can access this information. The following is the basics found in the store:

import { writable } from 'svelte/store';

export const info = writable({
  siteName: 'Svelte Website Template',
  byLine: 'For creating a great website from GitHub Pages.',
  address: 'http://localhost:5000',
  GitHub: 'https://raw.githubusercontent.com/',
  parts: ['test.html'],
  local: true,
  styles: {
    backgroundColor: '#D1BD79',
    backgroundPicture: '',
    borderColor: '#AA7942',
    divColor: '#ECDAAC',
    divBackgroundPicture: '',
    borderSize: '5px',
    borderRadius: '10px',
    textColor: 'black',
    font: '20px Times New Romand, Arial',
    headerFont: '20px Verdana, Arial',
    navFontSize: '24px',
    navHoverColor: 'blue',
    showSideBar: true,
    sideBarLeft: false,
    widthLogo: 920,
    widthNavbar: 700,
    widthSidebar: 900
  }
});

The first thing you will need to change is the siteName and byLine fields. These will have the name for your website and it's by-line. If you don't want a by-line, just leave it blank.

The address is the HTTP address for your local server. You will only need to change this if you change the port for your local server.

The GitHub address is the full path to your site folder when you upload to your GitHub pages repository. Once it is uploaded, go to the repository in GitHub, click on the site directory, then click on the 404.md file, and select the raw button on the right. You should now have the raw address to the 404.md file and see the contents in the browser. Copying the address should give you:

https://raw.githubusercontent.com/raguay/raguay.github.io/master/site/404.md

Put everything up to the site in the variable GitHub. It should look similar to:

    GitHub: 'https://raw.githubusercontent.com/raguay/raguay.github.io/master/site',

Of course, it will have the name of your account instead of my raguay account. This will be where the Page.svelte component will look for markdown pages for your site.

The parts variable is an array of names of files in the site/parts directory. Each file named here will be loaded into Handlebars as a partial. You can then include it on any markdown page using {{> 'test.html'}} macro. Each partial that is used causes some delay on loading the first markdown page. You might want to keep the ones you load to a minimum.

The local variable controls which address to use to get the pages: address or GitHub. If set to true, the the address address is used. Otherwise, the GitHub address is used. Make sure this is set to false and compiled before uploading to your GitHub site!

The styles object contains all the styling information for the site. Most of them are very self explanatory as they are named similar to the CSS properties. If the showSideBar variable is set to true, the side bar will be visible on the left side if sideBarLeft is true. It'll be on the right if sideBarLeft is false. If showSideBar is false, then no side bars will be shown and the content area will take the full with under the header.

There are three variables in the styles object that control responsive design feature. They are widthLogo, widthNavbar, and widthSidebar. The widthLogo variable is the pixel size that the logo will stop being displayed. The widthNavbar variable is the width that the navigation menu will go from horizontal to vertical. The widthSidebar variable is the width that the sidebar will no longer be displayed at. You can set these to values that makes sense for your site. A very short menu will not need as large of a value as a short menu will.

These variables can be set programmatically as well. That way, you can setup pages with the side bar or without. You could also set all the styling information from a menu entry to have different styles for each user. I'll most likely be adding more features for this in future versions of the template.

Each component that need information from the info store will have the following in it's script block:

  import { onMount } from 'svelte';
  import { info } from '../store/infoStore.js';

  let styles = {};

  onMount(() => {
    //
    // Subscribe to the information store to get the site information.
    //
    const unsubscribeInfo = info.subscribe((value) => {
      styles = value.styles;
    });

    return () => { unsubscribeInfo(); };
  });

The onMount function is imported from svelte and used to register a function that will run whenever the component is mounted to the DOM. The info store is loaded from the file that defines it. In the function ran by the onMount life cycle function will then register a function to run each time the library info is updated. That function set a component variable (I call it a shadow variable since it shadows the original store) to the new value of the store. When updated, it will trigger a refresh on the component. Now, you can use the information in the library in the template and in other functions. Just be careful that a function doesn't get called before the store's shadow variable isn't initialized.

When you subscribe to a store, the return value is the function to use to unsubscribe from the store. When you return from a onMount() function call, you return a function that calls the unsubscribe function to help free up memory and processing time for updates to the store. That function is called whenever the component is unmounted (or removed from the DOM).

If you need to make sure you have the latest information from a store before going forward with a function, you have to use the get function to get it from the store. The store variable that you load in isn't the actual store, but accessor function to it. You get the get function this way:

  import { get } from 'svelte/store';

You then use that function to get the most current value of the store. For example:

  var localvalue = get(info);

Now, you can use localvalue just like you did info in the template. This is a read only variable. You can't set values in the store by using the locally saved variable. To change a store's value, you use the set() method of the store. This only works if the new value is different (ie: 1 instead of 0). But for structures, this might not always be the case. Be careful.

Changing the Menus

The main menu on the website is in the NavBar.svelte component. It looks like this:

<div id='navbar' style="background-color: {styles.divColor};
                        background-image: {styles.divbackgroundPicture};
                        border: {styles.borderSize} solid {styles.borderColor};
                        border-radius: {styles.borderRadius};
                        color: {styles.textColor};" >
  <a class='navItem' href='/' use:link use:active>Home</a>
  <a class='navItem' href='/blog/index' use:link use:active>Blog</a>
  <a class='navItem' href='/about' use:link use:active>About</a>
</div>

<style>
  .navItem a {
    color: black;
    text-decoration-color: black;
  }

  #navbar {
    display: flex;
    flex-direction: row;
    width: 85%;
    margin: auto;
    border-radius: 10px;
    padding: 10px;
    margin-top: 10px;
    margin-bottom: 10px;
  }

  #navbar a {
    text-decoration: none;
    font-size: 24px;
  }

  .navItem {
    margin-right: 26px;
    text-decoration: none;
  }
</style>

<script>
  import { link } from 'svelte-spa-router';
  import active from 'svelte-spa-router/active';
  import { onMount } from 'svelte';
  import { info } from '../store/infoStore.js';

  let styles = {};

  onMount(() => {
    //
    // Subscribe to the information store to get the site information.
    //
    const unsubscribeInfo = info.subscribe((value) => {
      styles = value.styles;
    });

    return () => { unsubscribeInfo(); };
  });

</script>

The items of interest in the script block is the importing of the link and active commands. These are used in the template to define the anchor tags. The use:link action in the anchors will fix the references to the local SPA router style. A normal anchor reference would be /blog/index, the link action changes it to /#/blog/index. You don't have to use the link action, but it does make it a little easier to read.

The active action will show the link that is currently being displayed with the active class. You have to define your active class globally so that the name doesn't get specialize for the component. It is currently defined in the WebSite.svelte component in order to be only defined once. It looks like:

  :global(a.active) {
    color: #155393 !important;
    text-decoration-color: #155393;
  }

The :global() command tells Svelte that this is a globally defined CSS value and it should not be name mangled.

So, if you want to add a page call Favorites with the markdown file name of favorites.md, you would add the following to the list of anchor tags in the template:

  <a class='navItem' href='/favorites' use:link use:active>Favorites</a>

And make sure the file is in the site directory.

Changing the Main, Sidebar, and Footer Components

The main page (or more often referred to as the index page) is in the file Index.svexy file. It has the same layout as the About.svexy that we have already examined. Just add the markdown text you want in the main page. You can also include other components if needed.

The Sidebar is in the src/component/Sidebar.svelte component and the Footer is in the src/component/Footer.svelte component. They are nornal Svelte components that can be edited and changed as you need. Components like these that need to be edited are the reason I've made this a template and not a library. There is a src/components/Twitter.svelte and src/components/BlogPosts.svelte components that can be placed in the Sidebar as you want. I'll be creating more such components down the road.

Adding General and Blog Pages

The format of the site directory is as follow:

public/site
├── 404.md
├── blog
│   ├── index.md
│   └── my-first-post.md
└── parts
    └── test.html

Everything under the site directory is available to be sent as a page. The items in the parts directory can be seen as a page if they are markdown (ie: if the name of the file ends in .md). But, most partials will be HTML since they are not processed through the markdown and Handlebars processors. But, I think I will be doing that in the future.

Every page needs to be a markdown file with the ending .md. The files in a sub-directory are accessed as the path is normally seen. For example, the index for the blog page is /blog/index. For this reason, all directories should be a single word without and spaces or anything that isn't a letter or a number (ie: all punctuation and special symbols).

There isn't currently a process for building the index page for a blog. You will have to do that yourself. I'm working at adding a function to the Mask task runner for building the index pages from the post pages.

Every markdown page has to start with YAML head matter at the top. The minimum information is:

---
  title: The title of the blog
  date: 2019-11-26
---

The format is basically a name, :, and a value. The name has to be a single word. The date is given in the YYYY-MM-DD format. Each post can display it in any format given in the heading section as seen here:

## {{title}}
#### {{cdate date 'MMMM D, YYYY'}}

The date is taken from the YAML head matter and formatted using the cdate helper function. The format is the Moment.js formatting. You can change these to anything you want. This is just the formatting that I'm using on my site.

Each variable in the YAML head matter is also accessible using the Handlebar helpers just as the title was used in the above example.

The rest of the file is whatever markdown and text you want in your post or page.

Build and Deploying the Site

I'm assuming that you already have a GitHub Pages repository setup. If not, go ahead and do that. Once setup, clone the repository to the directory launch. That is best done by doing the git clone command in the templates directory, copy the files/directories in the launch directory to that cloned directory, delete the current launch directory, and rename the cloned git directory to launch. The build script will place all your site's information into the launch directory and upload it to GitHub.

Once the launch directory is setup, you can run:

mask build 'initial launching'

This will fully build the site, commit the changes to the git repository with the message given in single quotes, and push the changes to the GitHub repository for your GitHub pages site. Once GitHub Pages syncs, your new site will be live for everyone to see.

If you don't want to use Mask, then create a script with the following lines:

#!/bin/sh
npm run build
rm -Rf launch/js launch/css launch/imgs launch/site
mkdir launch/css launch/js
cp public/*.js launch/js
cp public/*.css launch/css
cp -Rf public/imgs launch/
cp -Rf public/site launch
cp public/CNAME launch
cd launch
git commit -am "$1"
git push

Then make the script executable using chmod a+x on the file. You should then be able to use that script instead of the Mask script.

The file CNAME is the name of your site if your using your own domain name server for the site. GitHub Pages will then use the name in that file as the name of the web-server for your site.

You only have to compile the full site each time you change a Svelte component. If you are simply adding markdown files to the public directory area, then you can just copy them to the launch area and commit them to GitHub.

Conclusion

Now that you know how to use this website template, go and make your own websites using it. Please let me know what sites you create with it so I can add it to the list on the template's GitHub page. That way, everyone can see who is using this template.