A person from the Philippines. I just Googled your username and it says it's a surname in the Philippines haha Feel free to write about anything you want, there are no penalties or interference of any kind.
hahahaha, Filipino? Is this a US term or are you referring to the ethnicity? My nickname kind of resembles something in tagalog if you mean that. I am a chemist (as you may have guessed) from Greece, still studying. I write about topics I am comfortable with.
Great news! If anything else comes up, ask away.
I checked now, the "multiple h1s" issue already has a "clear" message:
error: README.bigb:7:1: only one level 1 header is allowed in this conversion
(though at some point if people hit it often we can also add a link to a documentation section).
The missing Include possibility has a open ticket: github.com/ourbigbook/ourbigbook/issues/269
BTW, I'm curious at which level/which university/course you are at if you'd like to share that here or privately: ourbigbook.com/cirosantilli/contact This is totally optional of course. Philipino University undergrad is my guess (?) :-)
Thank you for your help! Basically everything would work if I had read the documentation correctly.
Some more things that I encountered as I tried to add a second article: Whenever I publish something new from my terminal, I am immediately logged off and I have to keep logging back in to make small changes to the articles that I have written.
I am aware of the logoff issue, and I will solve it soon, it's on the top of my list. I created a issue for it now: github.com/ourbigbook/ourbigbook/issues/325
One important thing though: there is currently no way to sync server -> local, only local -> server.
I really want to do this, but it is potentially hard because of how to handle merge conflicts. Which in turn requires some kind of history implementation for us to know who is outdated, local, server or both.
So for now, once you start doing things locally, don't ever edit on server, or else the next local push will just erase everything you edited on server.
I summarized this on a new ticket as I couldn't find one: github.com/ourbigbook/ourbigbook/issues/326
Also I couldn't publish a second article correctly. It seemed like name clashes were present, as I had made a second "references" section for the second article. But why is that? Shouldn't it all be allowed as the two "references" sections have different parents and thus are not identical.
To achieve that you have to use {scope} in both, this is what I was trying to say at: ourbigbook.com/go/discussion/1/pioyi/oveview and related docs: docs.ourbigbook.com/#h-scope-argument
Something like:
= Hydrogen sulfide
{scope}

== References

=== Book 1 by John Smith

= Hydrogen oxide
{scope}

== References

=== Book 2 by John Smith
which produces IDs/URLs:
/hydrogen-sulfide
/hydrogen-sulfide/references
/hydrogen-sulfide/book-1-by-john-smith
/hydrogen-oxide
/hydrogen-oxide/references
/hydrogen-oxide/book-2-by-john-smith
Without scope it would be:
/hydrogen-sulfide
/references
/book-1-by-john-smith
/hydrogen-oxide
/references
/book-2-by-john-smith
and so you get a conflict on references and it blows up.
I understand this is not how systems most people use work and it can be a bit confusing, but I strongly believe that this is a desirable feature and one of the great "innovations" of OurBigBook.
Already in this example we can see that /hydrogen-sulfide/book-1-by-john-smith is not a very good ID, we would rather want just /book-1-by-john-smith for it.
I.e., when you start scoping, how do you unscope things?
Or consider for example the insanely deep nodes that I have in my tree such as: ourbigbook.com/cirosantilli/sequence-and-organization-of-the-human-mitochondrial-genome-by-sanger-et-al-1981 at depth 40.
If we automatically added each ancestor ID to each ID, we would have IDs that don't even fit in allowed URLs anymore.
In order to get topics hits across multiple users, we need short IDs, and not auto scoping by ancestors by default is the best bet.
I remember that I published my first article with a hack that I have already forgotten. And this of course is not the standard way that you wanted. I find the publication process a bit too complex for a beginner, especially for one who has no knowledge of computer science! (thankfully I have some, but even this was not enough in my case. I even watched some videos on how to publish projects and yet I couldn't find a way that made me comfortable).
Again, I apologize for my misuse of the website. I am surely not reading the docs enough.
These are perfectly valid points, do criticize freely, and perhaps inevitable killer blows to the success of this project.
Ultimately, full user convenience can only come when WYSIWYG is done on Web UI and local, and perfect sync happens between them. Which I want to do. It's just a question of should I do content first to try and get regular users or after these potentially big tech steps (because as it may be obvious, I've done far too much tech, with far too few users besides myself to this point).
The scoping issue above is inevitable I believe: a "small" paradigm shift that makes our key innovation work (topics).
But regardless, things are definitely not forgiving now, and or not well explained well enough on intuitive UIs/error messages, and I want to get as close as possible to perfection in those points as I can.
Things are in this state for a mixture of reasons, good and bad.
A big part is of course my blind spots due to lack of other users, which makes feedback like yours extremely valuable.
But there is also a pragmatic feeling that at least initially, we are more likely to get a small number of huge users than a large number of small users, because small users only come from Google to web edit, and Google won't ever see us unless some big users put amazing content.
In any case, I will try to get as close as perfection in in-app explanations as I can and any ideas toward that are welcome. I want users to be able to discover how to do things as much as possible without reading the docs, definitely.
Is there a way to not have a new line every time I put some latex in the text?
Do you mean like inline vs block maths with $ vs $$? As in:
My inline $\sqrt{2}$ is nice.

My block:

$$
\sqrt{2}
$$

is also nice.
which renders as:
My inline is nice.
My block:
is also nice.
Doc at: docs.ourbigbook.com/#mathematics That syntax is directly inspired from LaTeX btw.
Also: My new article's structure looks like this:
You can do code blocks with triple backticks like in markdown btw (though we are better and also support double backticks only :-)): docs.ourbigbook.com/#code-block
``
= Bleach
{scope}

== Whatever
``
which renders as:
= Bleach
{scope}

== Whatever
That should work. Could you show me all files in your local directory?
Notably, do you have the above in a file called "bleach.big"? Or is it just inside your README.bigb?
If separate file, you need to include as:
README.bigb
= Index

\Include[bleach]
If same file as in:
= Index

= Bleach

== Whatever
then it doesn't work for web upload, because everything has to be a child of = Index to go into web tree (all web goes under a single root). So instead you need:
= Index

== Bleach

=== Whatever
I should, and will add a error message for that case btw if its getting silently ignored. I had tried to be more general from before Web existed, and something need to be slightly restricted to work on web.
This is one of those "needs a better error message on my blindspot" cases.
Oh had no idea this was the same markdown. meant to say: equals Bleach {scope}
equals equals whatever
Some more things that I encountered as I tried to add a second article: Whenever I publish something new from my terminal, I am immediately logged off and I have to keep logging back in to make small changes to the articles that I have written.
Also I couldn't publish a second article correctly. It seemed like name clashes were present, as I had made a second "references" section for the second article. But why is that? Shouldn't it all be allowed as the two "references" sections have different parents and thus are not identical. I am most probably missing something there, but I couldn't find an easy solution to my problem by reading the docs. (I keep my .bigb files in a separate directories and publish whichever one I want. I don't know if that's the correct way though.) I tried following your web editor suggestion and renaming my "references" section to "references | [article name]" but when executing the command, no changes were found.
I remember that I published my first article with a hack that I have already forgotten. And this of course is not the standard way that you wanted. I find the publication process a bit too complex for a beginner, especially for one who has no knowledge of computer science! (thankfully I have some, but even this was not enough in my case. I even watched some videos on how to publish projects and yet I couldn't find a way that made me comfortable).
Again, I apologize for my misuse of the website. I am surely not reading the docs enough.
P.S: Is there a way to not have a new line every time I put some latex in the text? Also: My new article's structure looks like this:
For some reason Bleach was never put as an actual section in the web, but instead all of the children nodes were published parentless. Why is that?
OK I fixed the homepage problem: ourbigbook.com/pioyi at: github.com/ourbigbook/ourbigbook/commit/e586bfa5cd977b55d16198193630cd892b4404b7 It was linked to an edge case of unlisted articles I hadn't tested.
Later on let me know how your local files look for --web upload. In principle, everything should work even if the articles already exist on server, it should just restructure everything to look exactly like your local output tree.
I'll check the homepage 500 issue. The more bugs found the better!
Also maybe some things to check (not that they are 100% bugs): 1) When viewing parent/children articles sometimes the dropdown menu doesn't work when clicked (the upside down triangle).
1) Do you mean on table of contents? It's currently broken: docs.ourbigbook.com/todo#toc-js-folding-broken-on-web I have to fix this, it just keep escaping the top of my list somehow.
2) My idea is to one day allow storing undeletable post history as well, so that when you link to someone's permalink, it NEVER ever goes down. This is similar to what Wikipedia and Stack Overflow do. If this ever becomes a problem we can reconsider, but generally speaking storage is cheap and CPU-hours are relatively expensive.
My new article seemed awesome when I previewed it via the index.html file but when I uploaded it (with --web) the inheritance was broken. Maybe that's because the article already existed and I tried to push it again! Yes, that makes sense.
I'll have a look at what you mean when I can restore your homepage :-) Also, if you manage to push your .bigb files into a github repo, that might help debug/understand issues (even though ultimately I should be able to figure it out from db).
I feel kind of bad for all the requests that I am making, I should preview my stuff before committing it.
Not at all, if anything comes up feel free to immediately comment without too much thinking. Because I have basically no users besides myself, any feedback is extremely valuable in guiding what I should do next.
Wow I must have seriously messed up. Not only did I manage to make duplicates of my current article, but also somehow got my home webpage to crash. I surely am a bad user! At least I got my local file uploaded, not in the way I wanted though (inheritance is not working as expected from the file structure. But that probably is my fault).
Also maybe some things to check (not that they are 100% bugs): 1) When viewing parent/children articles sometimes the dropdown menu doesn't work when clicked (the upside down triangle). 2) Why not just delete articles instead of unlisting them? Isn't it bad for the server's storage?
I feel kind of bad for all the requests that I am making, I should preview my stuff before committing it.
My new article seemed awesome when I previewed it via the index.html file but when I uploaded it (with --web) the inheritance was broken. Maybe that's because the article already existed and I tried to push it again! Yes, that makes sense.
Yes, give it a try and let me know if you face any issues. I want both to be amazing, but perhaps cli is a bit better now for those who can use it. Give the Visual Code Extension a try.
Thanks for all the tips. I will start using the cli version, it seems much more comfortable, at least for me
Oh that was really fast. I checked a few minutes ago and I though I was crazy. Nice work
Thank you so much for reporting this.
Dollar signs: by default dollar signs are for mathematics as in:
I like $\sqrt{1+1}$ as a number.
which renders as:
I like as a number.
To have a literal dollar you have to escape it with a backslash as in:
I have \$10 for lunch.
which renders as:
I have $10 for lunch.
The equals sign space: = would generate a header, but you can't create headers directly on the web editor. You should instead create new sections by just creating new articles with the New button. Then you set the parent to the other article as shown at: www.youtube.com/watch?v=yQRjLyqILl0 Note that the UI changed slightly from that older video, the parent selection is now under the "metadata" tab in the editor.
If you find any other issues or have any doubts do let me know and I'll try to fix/reply ASAP. This serious editor bug was there because I use mostly local editing, but I want the editor to work perfectly as well.
Pinned article: ourbigbook/introduction-to-the-ourbigbook-project
Welcome to the OurBigBook Project! Our goal is to create the perfect publishing platform for STEM subjects, and get university-level students to write the best free STEM tutorials ever.
Everyone is welcome to create an account and play with the site: ourbigbook.com/go/register. We belive that students themselves can write amazing tutorials, but teachers are welcome too. You can write about anything you want, it doesn't have to be STEM or even educational. Silly test content is very welcome and you won't be penalized in any way. Just keep it legal!
Video 1.
Intro to OurBigBook
. Source.
We have two killer features:
  1. topics: topics group articles by different users with the same title, e.g. here is the topic for the "Fundamental Theorem of Calculus" ourbigbook.com/go/topic/fundamental-theorem-of-calculus
    Articles of different users are sorted by upvote within each article page. This feature is a bit like:
    • a Wikipedia where each user can have their own version of each article
    • a Q&A website like Stack Overflow, where multiple people can give their views on a given topic, and the best ones are sorted by upvote. Except you don't need to wait for someone to ask first, and any topic goes, no matter how narrow or broad
    This feature makes it possible for readers to find better explanations of any topic created by other writers. And it allows writers to create an explanation in a place that readers might actually find it.
    Figure 1.
    Screenshot of the "Derivative" topic page
    . View it live at: ourbigbook.com/go/topic/derivative
    Video 2.
    OurBigBook Web topics demo
    . Source.
  2. local editing: you can store all your personal knowledge base content locally in a plaintext markup format that can be edited locally and published either:
    • to OurBigBook.com to get awesome multi-user features like topics and likes
    • as HTML files to a static website, which you can host yourself for free on many external providers like GitHub Pages, and remain in full control
    This way you can be sure that even if OurBigBook.com were to go down one day (which we have no plans to do as it is quite cheap to host!), your content will still be perfectly readable as a static site.
    Figure 5. . You can also edit articles on the Web editor without installing anything locally.
    Video 3.
    Edit locally and publish demo
    . Source. This shows editing OurBigBook Markup and publishing it using the Visual Studio Code extension.
    Video 4.
    OurBigBook Visual Studio Code extension editing and navigation demo
    . Source.
  3. https://raw.githubusercontent.com/ourbigbook/ourbigbook-media/master/feature/x/hilbert-space-arrow.png
  4. Infinitely deep tables of contents:
    Figure 6.
    Dynamic article tree with infinitely deep table of contents
    .
    Descendant pages can also show up as toplevel e.g.: ourbigbook.com/cirosantilli/chordate-subclade
All our software is open source and hosted at: github.com/ourbigbook/ourbigbook
Further documentation can be found at: docs.ourbigbook.com
Feel free to reach our to us for any help or suggestions: docs.ourbigbook.com/#contact