search

jupyter-book / mystmd

Command line tools for working with MyST Markdown.
https://mystmd.org/guide
MIT License
201 stars 61 forks source link

Minimal example project repo #219

Open kolibril13 opened 1 year ago

kolibril13 commented 1 year ago

Which area is this feature request for?

Other

Describe the feature you'd like to request

It'd be amazing to have a minimal example repo! And I would have some free hours to write that minimal example ✍️

Describe the solution you'd like

I've already created a repo here (https://github.com/kolibril13/mystjs-minimal-example). Before I fill it with content, I was thinking of how to host this. Is there already an option to use GitHub pages for that? Looking at https://github.com/executablebooks/mystjs/issues/188 it seems there is no option for that by now.

@rowanc1, can I use your server that also hosts https://myst-tools.org/docs/mystjs to run this minimal example? In my opinion, it would be important that the minimal example lives in a separate repo and on a separate webpage, so that people can explore without getting overwhelmed.

The minimal example will be similar to the https://github.com/executablebooks/mystjs-quickstart guide. But the difference: this minimal example won't have to be transformed throughout a tutorial. Instead, all mystjs syntax will be already in place for people to explore.

Also, the current quick-start has a docs-in-docs narrative, which I sometimes find a bit mind-bending. This minimal example content will instead be about another topic that is not related to myst.

Describe alternatives you've considered

No response

rowanc1 commented 1 year ago

Yes please! If you have a vision for a minimal example, I would love to see you run with that and we can work it into the docs for others to see! #202 also has some pointers to resources that might be helpful.

The easiest way to deploy at the moment is to use curvenote deploy (see deployment docs). Curvenote was upstreamed to myst over the last few months, and we haven't got all the deployment things easy from the myst side yet. It is bubbling up to the top of the priority list I think!

Certainly static HTML is one option, another option is to use vercel or netlify, which work today but do require a place to host the static content (e.g. curvenote or in the future, github as the CDN for the static json).

kolibril13 commented 1 year ago

Yep, my vision is a document that shows the bare minimum of all core features. The goal is to keep things as simple as possible. That way, people can explore the main myst features without having everything at once.

This is what the minimal example will contain:

Lorem Ipsum... +++



* one figure
* one equation
* one table
* one code block
* cross-reference to citation, figure, equation, table and code block
* one citation
* one admonition
* one footnote
* one bold word
rowanc1 commented 1 year ago

Nice - that would be very much appreciated! Right now the mystjs-quickstart is kinda the opposite of that, as it is something that is plain markdown that is improved through the tutorial.

I think this is something that we would eventually like in the EBP organization, especially if it is un-opinionated. Would you be up for iterating on the repo that you have already created with the idea of bringing that into the EBP organization in the future? (we could also do that right away if you want -- regardless, would love to keep you as the leader of this effort!)

Let me know if that is something you want to explore!

kolibril13 commented 1 year ago

A first version of the minimal example is now ready here: https://github.com/kolibril13/mystjs-minimal-example And this is a sandbox link (github does not want to show this as a clickable link though :D ): EDIT: Same link, but as tinyurl: https://tinyurl.com/myst-sandbox-euler https://myst-tools.org/sandbox?tab=demo&myst=LQAtAC0ACgB0AGkAdABsAGUAOgAgAEUAdQBsAGUAcgAnAHMAIABpAGQAZQBuAHQAaQB0AHkACgBzAHUAYgBqAGUAYwB0ADoAIABNAGEAdABoAAoAcwB1AGIAdABpAHQAbABlADoAIABMAG8AcgBlAG0AIABpAHAAcwB1AG0AIABkAG8AbABvAHIAIABzAGkAdAAuAAoAcwBoAG8AcgB0AF8AdABpAHQAbABlADoAIABFAHUAbABlAHIACgBhAHUAdABoAG8AcgBzADoACgAgACAALQAgAG4AYQBtAGUAOgAgAEoAbwBoAG4AIABEAG8AZQAKACAAIAAgACAAYQBmAGYAaQBsAGkAYQB0AGkAbwBuAHMAOgAKACAAIAAgACAAIAAgAC0AIABVAG4AaQB2AGUAcgBzAGkAdAB5ACAAbwBmACAAQgBhAHMAZQBsAAoAIAAgACAAIABlAG0AYQBpAGwAOgAgAG4AYQBtAGUAQABzAHUAcgBuAGEAbQBlAC4AYwBvAG0ACgBsAGkAYwBlAG4AcwBlADoAIABDAEMALQBCAFkALQA0AC4AMAAKAGsAZQB5AHcAbwByAGQAcwA6ACAAbQB5AHMAdAAsACAAbQBhAHIAawBkAG8AdwBuACwAIABvAHAAZQBuAC0AcwBjAGkAZQBuAGMAZQAKAG4AdQBtAGIAZQByAGkAbgBnADoACgAgACAAYwBvAGQAZQA6ACAAdAByAHUAZQAgAAoAIAAgACMAIABUAE8ARABPADoAIABjAG8AZABlADoAIAB0AHIAdQBlACAAbQBpAGcAaAB0ACAAYgBlACAAZABlAGYAYQB1AGwAdAAgAGkAbgAgAGYAdQB0AHUAcgBlAAoACgBlAHgAcABvAHIAdABzADoACgAgACAALQAgAGYAbwByAG0AYQB0ADoAIABwAGQAZgAKACAAIAAgACAAdABlAG0AcABsAGEAdABlADoAIABhAHIAeABpAHYAXwB0AHcAbwBfAGMAbwBsAHUAbQBuAAoALQAtAC0ACgAKACsAKwArACAAewAiAHAAYQByAHQAIgA6ACAAIgBhAGIAcwB0AHIAYQBjAHQAIgB9AAoACgBMAG8AcgBlAG0AIABpAHAAcwB1AG0AIABkAG8AbABvAHIAIABzAGkAdAAgAGEAbQBlAHQALAAgAGMAbwBuAHMAZQBjAHQAZQB0AHUAcgAgAGEAZABpAHAAaQBzAGMAaQBuAGcAIABlAGwAaQB0ACwAIABzAGUAZAAgAGQAbwAgAGUAaQB1AHMAbQBvAGQAIAB0AGUAbQBwAG8AcgAgAGkAbgBjAGkAZABpAGQAdQBuAHQAIAB1AHQAIABsAGEAYgBvAHIAZQAgAGUAdAAgAGQAbwBsAG8AcgBlACAAbQBhAGcAbgBhACAAYQBsAGkAcQB1AGEALgAgAE0AYQBzAHMAYQAgAHQAaQBuAGMAaQBkAHUAbgB0ACAAZAB1AGkAIAB1AHQAIABvAHIAbgBhAHIAZQAgAGwAZQBjAHQAdQBzACAAcwBpAHQAIABhAG0AZQB0ACAAZQBzAHQAIABwAGwAYQBjAGUAcgBhAHQALgAKACsAKwArAAoAIwAgAEkAbgB0AHIAbwAKAE0AYQBuAHkAIAAqACoAcABoAGUAbgBvAG0AZQBuAGEAKgAqACAAYQByAGUAIABkAGUAcwBjAHIAaQBiAGUAZAAgAGIAeQAgAEUAdQBsAGUAcgAnAHMAIABpAGQAZQBuAHQAaQB0AHkAIAAgAFsAXQAoACMAbQB5AC0AZQBxACkALgAgACAACgBJAHQAJwBzACAAdQBzAGUAZAAgAGkAbgAgAHQAaABlACAAdwBhAHYAZQAgAGUAcQB1AGEAdABpAG8AbgBbAF4AbQB5AHIAZQBmAF0ALgAgACAACgBNAG8AcgBlACAAaQBuACAAWwBdACgAIwBtAHkALQBmAGkAZwApACwAIABbAF0AKAAjAG0AeQAtAHAAcgBvAGcAcgBhAG0AKQAgAGEAbgBkACAAWwBdACgAIwBlAHgAYQBtAHAAbABlAC0AdABhAGIAbABlACkALgAgACAACgBBAGwAcwBvACAAcwBlAGUAIAAgAFsAVwBpAGsAaQBwAGUAZABpAGEAXQAoAGgAdAB0AHAAcwA6AC8ALwBlAG4ALgB3AGkAawBpAHAAZQBkAGkAYQAuAG8AcgBnAC8AdwBpAGsAaQAvAEUAdQBsAGUAcgAlADIANwBzAF8AaQBkAGUAbgB0AGkAdAB5ACkALgAgACAACgBBAG4AZAAgAGEAIABwAGEAcABlAHIAIABoAGUAcgBlACAAWwBdACgAZABvAGkAOgAxADAALgA0ADIAMwAwAC8ARABBAEcATQBBAE4ALgAxAC4AMQAuADQAMQApAC4AIAAgAAoACgBbAF4AbQB5AHIAZQBmAF0AOgAgAFYAZQByAHkAIAB1AHMAZQBmAHUAbAAhAAoAIwAgAEUAeABhAG0AcABsAGUAIAAKAAoATABvAHIAZQBtACAAaQBwAHMAdQBtACAAZABvAGwAbwByACAAcwBpAHQAIABhAG0AZQB0ACwAIABjAG8AbgBzAGUAYwB0AGUAdAB1AHIAIABhAGQAaQBwAGkAcwBjAGkAbgBnACAAZQBsAGkAdAAsACAAcwBlAGQAIABkAG8AIABlAGkAdQBzAG0AbwBkACAAdABlAG0AcABvAHIAIABpAG4AYwBpAGQAaQBkAHUAbgB0ACAAdQB0ACAAbABhAGIAbwByAGUAIABlAHQAIABkAG8AbABvAHIAZQAgAG0AYQBnAG4AYQAgAGEAbABpAHEAdQBhAC4ACgAKACQAJABlAF4AewBpAHgAfQA9AFwAYwBvAHMAKAB4ACkAKwBpAFwAcwBpAG4AKAB4ACkAIAAkACQAIAAgACgAbQB5AC0AZQBxACkACgAKADoAOgA6AHsAZgBpAGcAdQByAGUAfQAgAGgAdAB0AHAAcwA6AC8ALwBpAG0AYQBnAGUAcwAuAHAAZQB4AGUAbABzAC4AYwBvAG0ALwBwAGgAbwB0AG8AcwAvADQAMAA3ADgANAAvAGQAcgBvAHAAcwAtAG8AZgAtAHcAYQB0AGUAcgAtAHcAYQB0AGUAcgAtAG4AYQB0AHUAcgBlAC0AbABpAHEAdQBpAGQALQA0ADAANwA4ADQALgBqAHAAZQBnAAoAOgBuAGEAbQBlADoAIABtAHkALQBmAGkAZwAKADoAdwBpAGQAdABoADoAIAAzADAAMABwAHgACgA6AGEAbAB0ADoAIABBACAAZAByAG8AcAAgAG8AZgAgAHcAYQB0AGUAcgAuAAoACgBBACAAIAB3AGEAdABlAHIAIAB3AGEAdgBlAAoAOgA6ADoACgAKAGAAYABgAHsAYwBvAGQAZQAtAGIAbABvAGMAawB9ACAAcAB5AHQAaABvAG4ACgA6AG4AYQBtAGUAOgAgAG0AeQAtAHAAcgBvAGcAcgBhAG0ACgA6AGMAYQBwAHQAaQBvAG4AOgAgAEMAYQBsAGMAdQBsAGEAdABpAG8AbgAgAHcAaQB0AGgAIABuAHUAbQBwAHkALgAKAGkAbQBwAG8AcgB0ACAAbgB1AG0AcAB5ACAAYQBzACAAbgBwAAoACgBjACAAPQAgAGEAIAArACAAYgAqADEAagAKAHAAcgBpAG4AdAAoAG4AcAAuAHIAZQBhAGwAKABjACkAKQAKAHAAcgBpAG4AdAAoAG4AcAAuAGkAbQBhAGcAKABjACkAKQAKAGAAYABgAAoACgA6ADoAOgB7AGwAaQBzAHQALQB0AGEAYgBsAGUAfQAgAFQAcgBhAG4AcwBsAGEAdABlACAAZgByAG8AbQAgAHIAYQBkAGkAYQBuACAAdABvACAAZABlAGcAcgBlAGUACgA6AGgAZQBhAGQAZQByAC0AcgBvAHcAcwA6ACAAMQAKADoAbgBhAG0AZQA6ACAAZQB4AGEAbQBwAGwAZQAtAHQAYQBiAGwAZQAKAAoAKgAgAC0AIABSAGEAZAAKACAAIAAtACAARABlAGcACgAqACAALQAgADMALgAxADQACgAgACAALQAgADEAOAAwAAoAKgAgAC0AIAA2AC4AMgA4AAoAIAAgAC0AIAAzADYAMAAKADoAOgA6AAoACgA6ADoAOgB7AG4AbwB0AGUAfQAKADoAYwBsAGEAcwBzADoAIABkAHIAbwBwAGQAbwB3AG4ACgBMAG8AcgBlAG0AIABpAHAAcwB1AG0AIABkAG8AbABvAHIAIABzAGkAdAAgAGEAbQBlAHQAIAAKADoAOgA6AAoACgAgADwAIQAtAC0AIABGAG8AcgAgAHAAZABmACAAZQB4AHAAbwByAHQALAAgAHIAdQBuACAAYABtAHkAcwB0ACAAYgB1AGkAbABkACAAMAAxAC0AaABlAGwAbABvAC4AbQBkAGAAIAAtAC0APgA%3D

rowanc1 commented 1 year ago

This looks awesome! Nice work!

Apparently GitHub limits links at 4096 characters. Probably fair. We could probably host a small database behind the sandbox for long links.

Also remembering that DOIs don't work in the sandbox yet, and apparently not HTML comments either.

kolibril13 commented 1 year ago

With a random letter compression algorithm that I found on the internet (http://www.unit-conversion.info/texttools/compress/), it was possible to reduce the string from 4536 to 2360 characters. A small database is a good idea, but I also really like these long links that contain all information! :)

kolibril13 commented 1 year ago

Settings for this tweet https://twitter.com/kolibril13/status/1628168155473358848:
Google Chrome, https://myst-tools.org/sandbox, Zoom 150% """

A

:::{figure} https://images.pexels.com/photos/40784/drops-of-water-water-nature-liquid-40784.jpeg :width: 300px :name: my-fig :alt: A drop of water.

A falling drop of water :::

Lorem ipsum dolor sit amet. eos nostrum ipsum et unde omnis qui galisum quaerat et enim neque.

B

numbering: code: true 

:name: my-program
:caption: Calculation with numpy.

import numpy as np

c = a + b*1j
print(np.real(c))
print(np.imag(c))

Lorem ipsum dolor sit amet. eos nostrum ipsum et unde omnis qui galisum quaerat et enim neque.

C

$$e^{ix}=\cos(x)+i\sin(x) $$ (my-eq)

Lorem ipsum dolor sit amet. eos nostrum ipsum et unde omnis qui galisum quaerat et enim neque.

D

title: Euler's identity subject: Math subtitle: Lorem ipsum dolor sit. authors:

corentinmorice1 commented 1 year ago

Thanks a lot for setting this up! I'm trying to use https://github.com/kolibril13/mystjs-minimal-example as a basis for setting up my own test repo https://github.com/corentinmorice1/myst-test. I use exactly the same workflow and the same myst.yml. Github actions runs just fine. But somehow the website is not uploaded. Would you know what could be happening?

kolibril13 commented 1 year ago

hey @corentinmorice1 , glad you found this useful. You're project is set up correctly, see https://corentinmorice1.github.io/myst-test/notebook https://corentinmorice1.github.io/myst-test/paper

the only thing is that you probably should rename your readme from readme.md to readme.txt

corentinmorice1 commented 1 year ago

Sorry, the answer was already given in https://github.com/executablebooks/mystjs/issues/430. I just hadn't changed the build and deployment branch to gh-pages. Thanks a lot for your kind reply @kolibril13 !

rowanc1 commented 1 year ago

That is awesome @corentinmorice1, glad you are sorted! @kolibril13 I have a local github action as well that doesn't use the gh-pages branch that is over here: https://github.com/rowanc1/myst-lite That is using a few cutting edge thebe things that @stevejpurves has been putting together for JupyterLite!