Written some text
This commit is contained in:
Eduardo Cueto Mendoza
parent
524dda88de
commit
538642b269
|
|
@ -1,55 +0,0 @@
|
||||||
@def hascode = true
|
|
||||||
|
|
||||||
# FAQ - Troubleshooting
|
|
||||||
|
|
||||||
This page is about some of the known errors you may encounter when using Franklin and how to deal with them.
|
|
||||||
If you encounter an error that is not mentioned here, then it's probably a bug and it would be great if you could open an issue!
|
|
||||||
|
|
||||||
\toc
|
|
||||||
|
|
||||||
## Error on interruption
|
|
||||||
|
|
||||||
You may (rarely) get an an error thrown at you when interrupting the server with `<CTRL>+C`, particularly when using Juno.
|
|
||||||
There are a couple of reasons this may happen, both unrelated to Franklin.
|
|
||||||
|
|
||||||
### Juno
|
|
||||||
|
|
||||||
Juno (very rarely) crashes if you coincidentally press `<CTRL>+C` while Juno is doing something in the background (Juno issue [#309](https://github.com/JunoLab/Juno.jl/issues/309)).
|
|
||||||
|
|
||||||
The stacktrace you will see will seem particularly obscure, for instance:
|
|
||||||
|
|
||||||
```
|
|
||||||
InterruptException:
|
|
||||||
_string_n at string.jl:60 [inlined]
|
|
||||||
StringVector at iobuffer.jl:31 [inlined]
|
|
||||||
#IOBuffer#320(::Bool, ::Bool, ::Nothing, ::Bool, ::Int64, ::Int64, ::Type{Base.GenericIOBuffer{Array{UInt8,1}}}) at iobuffer.jl:114
|
|
||||||
(...)
|
|
||||||
```
|
|
||||||
|
|
||||||
or
|
|
||||||
|
|
||||||
```
|
|
||||||
julia> "miniERROR: InterruptException:
|
|
||||||
Stacktrace:
|
|
||||||
[1] poptaskref(::Base.InvasiveLinkedListSynchronized{Task}) at ./task.jl:564
|
|
||||||
[2] wait() at ./task.jl:591
|
|
||||||
(...)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Solution**: ignore the error, kill then restart the server or, failing that, kill and restart Julia.
|
|
||||||
|
|
||||||
### Not-Juno
|
|
||||||
|
|
||||||
The [`LiveServer.jl`](https://github.com/asprionj/LiveServer.jl) package, which handles the live-serving of the files, is based upon [`HTTP.jl`](https://github.com/asprionj/LiveServer.jl).
|
|
||||||
The latter has a fairly complex codebase with a number of asynchronous tasks and is known to sometimes crash in (somewhat) mysterious ways.
|
|
||||||
|
|
||||||
If the stacktrace mentions `uv_write`, `uv_write_async`, `libuv` or something of the sorts, then this is an example of _known but mysterious way_.
|
|
||||||
|
|
||||||
Like the "Juno" case, these errors are caused when you happen to press interrupt just as the package was doing something important in the background.
|
|
||||||
This is very rare but can happen and you can safely ignore it.
|
|
||||||
|
|
||||||
**Solution**: ignore the error, kill then restart the server or, failing that, kill and restart Julia.
|
|
||||||
|
|
||||||
## IOStream error
|
|
||||||
|
|
||||||
See the comment about HTTP.jl in the [subsection above](#Not-Juno-1).
|
|
||||||
66
index.md
66
index.md
|
|
@ -30,68 +30,4 @@ end
|
||||||
|
|
||||||
## A bit about myself
|
## A bit about myself
|
||||||
|
|
||||||
My interest in science started from a very early age I was in love with physics because a teacher in elementary school had a copy of the book `COSMOS` which he lend me and I was marveled by the words of [Carl Sagan](https://en.wikipedia.org/wiki/Carl_Sagan)
|
My interest in science started from a very early age I was in love with physics because a teacher in elementary school had a copy of the book `COSMOS` which he lend me and I was marveled by the words of [Carl Sagan](https://en.wikipedia.org/wiki/Carl_Sagan)
|
||||||
|
|
||||||
<!--
|
|
||||||
# Building static websites in Julia
|
|
||||||
|
|
||||||
\blurb{Franklin is a simple, customisable static site generator oriented towards technical blogging and light, fast-loading pages.}
|
|
||||||
|
|
||||||
## Key features
|
|
||||||
|
|
||||||
@@flist
|
|
||||||
* \goto{/syntax/markdown/} Augmented markdown allowing definition of LaTeX-like commands,
|
|
||||||
* \goto{/syntax/divs-commands/} Easy inclusion of user-defined div-blocks,
|
|
||||||
* \goto{/syntax/divs-commands/} Maths rendered via [KaTeX](https://katex.org/), code via [highlight.js](https://highlightjs.org) both can be pre-rendered,
|
|
||||||
* \goto{/code/} Can live-evaluate Julia code blocks,
|
|
||||||
* \goto{/workflow/#creating_your_website} Live preview of modifications,
|
|
||||||
* \goto{/workflow/#optimisation_step} Simple optimisation step to compress and pre-render the website,
|
|
||||||
* \goto{/workflow/#publication_step} Simple publication step to deploy the website,
|
|
||||||
* \goto{/code/literate/} Straightforward integration with [Literate.jl](https://github.com/fredrikekre/Literate.jl).
|
|
||||||
@@
|
|
||||||
|
|
||||||
## Quick start
|
|
||||||
|
|
||||||
To install Franklin with Julia **≥ 1.3**,
|
|
||||||
|
|
||||||
```julia-repl
|
|
||||||
(v1.4) pkg> add Franklin
|
|
||||||
```
|
|
||||||
|
|
||||||
You can then just try it out:
|
|
||||||
|
|
||||||
```julia-repl
|
|
||||||
julia> using Franklin
|
|
||||||
julia> newsite("mySite", template="pure-sm")
|
|
||||||
✓ Website folder generated at "mySite" (now the current directory).
|
|
||||||
→ Use serve() from Franklin to see the website in your browser.
|
|
||||||
|
|
||||||
julia> serve()
|
|
||||||
→ Initial full pass...
|
|
||||||
→ Starting the server...
|
|
||||||
✓ LiveServer listening on http://localhost:8000/ ...
|
|
||||||
(use CTRL+C to shut down)
|
|
||||||
```
|
|
||||||
|
|
||||||
If you navigate to that URL in your browser, you will see the website. If you then open `index.md` in an editor and modify it at will, the changes will be live rendered in your browser.
|
|
||||||
You can also inspect the file `menu1.md` which offers more examples of what Franklin can do.
|
|
||||||
|
|
||||||
## Installing optional extras
|
|
||||||
|
|
||||||
Franklin allows a post-processing step to compress HTML and CSS and pre-render code blocks and math environments.
|
|
||||||
This requires a couple of dependencies:
|
|
||||||
@@tlist
|
|
||||||
* [`python3`](https://www.python.org/downloads/) for the minification of the site,
|
|
||||||
* [`node.js`](https://nodejs.org/en/) for the pre-rendering of KaTeX and code highlighting.
|
|
||||||
@@
|
|
||||||
You will then need to install `highlight.js`, which you should do from Julia using the [NodeJS.jl](https://github.com/davidanthoff/NodeJS.jl) package:
|
|
||||||
|
|
||||||
```julia-repl
|
|
||||||
julia> using NodeJS
|
|
||||||
julia> run(`sudo $(npm_cmd()) install highlight.js`)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Note**: a key advantage of using `NodeJS` for this instead of using `npm` yourself is that it puts the libraries in the "right place" for Julia to find them.
|
|
||||||
|
|
||||||
Assuming you have `python3`, Franklin will try to install the python package [`css_html_js_minify`](https://github.com/juancarlospaco/css-html-js-minify) if via `pip3`.
|
|
||||||
-->
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue