Main functions

The two main functions exported by the package are

• serve and
• servedocs,

they are discussed in some details here.

serve

The exported serve function is the main function of the package. The basic usage is

julia> cd("directory/of/website")
julia> serve()
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

which will make the content of the folder available to be viewed in a browser.

You can specify the port that the server should listen to (default is 8000) as well as the directory to serve (if not the current one) as keyword arguments. There is also a verbose keyword-argument if you want to see messages being displayed on file changes and connections.

More interestingly, you can optionally specify the filewatcher (the only regular argument) which allows to define what will trigger the messages to the client and ultimately cause the active browser tabs to reload. By default, it is file modifications that will trigger page reloads but you may want to write your own file watcher to perform additional actions upon file changes or trigger browser reload differently.

Finally, you can specify a function coreloopfun which is called continuously while the server is running. There may be circumstances where adjusting coreloopfun helps to complement the tuning of a FileWatcher.

See the section on Extending LiveServer for more informations.

servedocs

The exported servedocs function is a convenient function derived from serve. The main purpose is to allow Julia package developpers to live-preview their documentation while working on it by coupling Documenter.jl and LiveServer.jl.

Let's assume the structure of your package looks like

.
├── LICENSE.md
├── Manifest.toml
├── Project.toml
├── README.md
├── docs
│   ├── Project.toml
│   ├── build
│   ├── make.jl
│   └── src
│       └── index.md
├── src
│   └── MyPackage.jl
└── test
    └── runtests.jl

The standard way of running Documenter.jl is to run make.jl, wait for completion and then use a standard browser or maybe some third party tool to see the output.

With servedocs however, you can edit the .md files in your docs/src and see the changes being applied directly in your browser which makes writing documentation faster and easier. To launch it, navigate to YourPackage.jl/ and simply

julia> using YourPackage, LiveServer
julia> servedocs()

This will execute make.jl (a pass of Documenter.jl) before live serving the resulting docs/build folder with LiveServer.jl. Upon modifying a .md file (e.g. updating docs/src/index.md), the make.jl will be applied and the corresponding changes propagated to active tabs (e.g. a tab watching http://localhost:8000/index.html)

Additional keywords

The servedocs function now takes extra keywords which may, in some cases, make your life easier:

• foldername="docs", is the name of folder that contains the documentation, which can be changed if it's different than docs.
• doc_env=false, if set to true, the Project.toml available in docs/ will be activated (note 1),
• skip_dir="", indicates a directory to skip when looking at the docs folder for change, this can be useful when using packages like Literate or Weave that may generate files inside your src folder.

Note that in latter two cases these keywords are there for your convenience but would be best not used. See also the discussion in this issue. In the first case, doing

julia --project=docs -e 'using LiveServer; servedocs()'

is more robust.

In the second case, it would be best if you made sure that all generated files are saved in docs/build/....