3. Creating a new site

3.1 Copy the script

First of all, copy the script for instance in ~/bin

$ cp mkdocs-et.sh ~/bin

and make sure that ~/bin is in your PATH.

Create a new directory for your project

$ mkdir mysite && cd mysite
mysite$

and run the script

mysite$ mkdocs-et.sh

to see if it works.

We suppose that you already have created a virtual environment (in the tutorial).

3.2 Create a skeleton

Simply type

mysite$ mkdocs-et.sh create-skel

Creating skeleton directory skel-mkdocs-et...
  + skel-mkdocs-et/images/
  + skel-mkdocs-et/includes/
  + skel-mkdocs-et/javascripts/
  + skel-mkdocs-et/stylesheets/
  + skel-mkdocs-et/overrides/
  + skel-mkdocs-et/htaccess
  + skel-mkdocs-et/conf-mkdocs-et.sh
  + skel-mkdocs-et/mkdocs.yml
  + skel-mkdocs-et/javascripts/config.js
  + skel-mkdocs-et/stylesheets/extra.css
  + skel-mkdocs-et/overrides/main.html
  + index.md
Skeleton directory skel-mkdocs-et created.

Then run the embedded server

mysite$ mkdocs-et.sh serve --all

and open your browser on http://localhost:8000/ ¹

You can start to edit index.md, and save it each time you want to see the result in the browser.

3.3 Configure

In the file skel-mkdocs-et/conf-mkdocs-et.sh, change the following items:

# Your login on the target web server
TARGET_HOST="mylogin@myserver.fr"

# Base directory on the target server
TARGET_DIR="~/public_html/mysite"

Also check that you can ssh to your server without a password, else copy your public ssh key.

Edit skel-mkdocs-et/mkdocs.yml and enter the main informations at the beginning:

# Project information
site_name: Mysite
site_url: http://myserver.fr/~mylogin/mysite
site_author: My name
site_description: My site using Mkdocs-et

# Copyright: for instance CC BY-SA
copyright: CC BY-SA - myemail@myprovider.fr

# Bottom right "Home page" link
extra:
  social:
    - icon: fontawesome/solid/house
      link: http://myserver.fr/~mylogin/

# Configuration
theme:
  name: material
  # Select here your language: en, fr, ...
  language: en
  # Select here the colors of your theme
  palette:
    primary: 'green'
    accent: 'deep orange'

To select the primary color of your theme, see the online selector.

The favicon is also defined there, you may remove it, or copy yours in skel-mkdocs-et/images/.

Other settings can be made later in the file, see the comments inside, an also here.

3.4 Publish your site

Interrupt the script with Ctrl+c, then mirror your site to the target server with

mysite$ mkdocs-et.sh publish --all

See also here to filter the page or force the mirroring.

Open you browser on the resulting URL, perhaps something like

http://myserver.fr/~mylogin/mysite

3.5 Adding a page

Edit a new file, say pagetwo.md, with a # Title; then edit skel-mkdocs-et/conf-mkdocs-et.sh and add an entry for the page, for instance

    "|pagetwo.md|Page Two"

in one of the NAV_BEGIN or NAV_END list. To put a new page in the filtered list, see here.

Rerun the embedded server to watch the result:

mysite$ mkdocs-et.sh serve --all

Note :

If the script warn you about a syntax error in the config file, interrupt it, correct the syntax (if not already done) and rerun it. You will probably have also to reload the page in the browser.

The same if a new page is not found, or a filename has changed.

---

1. if the port 8000 is already in use, try another one, for example 8001, by running mkdocs-et.sh serve --all -p 8001 ↩