Search index completely empty

[marcelstoer]

The search index for http://nodemcu.readthedocs.org/ appears to be completely empty. No matter what I search I get are zero results. Examples: https://readthedocs.org/projects/nodemcu/search/?q=NodeMCU , https://readthedocs.org//search/?q=ESP8266&check_keywords=yes&area=default&project=nodemcu&version=dev&type=file

I didn't see anywhere that I'd have to configure the search feature(s). Hence, I couldn't possibly have _mis_configured anything, could I?

[agjohnson]

Not sure what the state of Mkdocs search is, there are a few tickets open about it. Sphinx + Markdown will give you full search results, if there isn't anything tying you to mkdocs. Closing this here as there are a few tickets open already on issues with mkdocs and search.

[marcelstoer]

Gee, what's wrong with me and GitHub search? I did query your open issues for search before I submitted this but only now when I looked for Mkdocs search did I see the relevant ones. Adding here for the sake of completeness: #1088 (primary), #1487 (a dup IMO), #1633.

The last one is particularly interesting because it affects an MkDocs project for which RTD search DOES work. Any idea why?

Sphinx + Markdown will give you full search results, if there isn't anything tying you to mkdocs.

For what it's worth: CommonMark, at least in its current state, is a no-go for me.

[agjohnson]

Ah yes, those are some of the ones I was referring to, but too rushed to link to :)

We haven't had time to revisit search and Mkdocs in a while, I do know of cases where it is working though. There seems to be a number of cases where, I assume, we're not loading the index correctly.

[marcelstoer]

If it works for some Mkdocs projects but not for others there's nothing I can do, right?

[sahilTakiar]

@marcelstoer just curious, any reason CommonMark isn't an option for you? I have been considering using it too, as an alternative to MkDocs. Since CommonMark integrates with Sphinx I though it could be quite useful: http://blog.readthedocs.com/adding-markdown-support/

[marcelstoer]

any reason CommonMark isn't an option for you?

Sure, since this issue is already closed anyway we might as well stroll into off-topic territory here. I don't claim to be intimately familiar with CommonMark but I did spend a few hours "analyzing" the project before I decided to go with MkDocs.

While I generally welcome markdown standardization efforts CommonMark just progresses painstakingly slow IMO. I appreciated the team is trying to get everything right the first time but this also means there's endless discussion about every tiny detail. For now all they cared about were the markdown basics. To me CommonMark is no good if it doesn't incorporate markdown features or "extensions" that became de-facto standards over the years right from the start.
The most obvious example of this is the missing table support, see http://talk.commonmark.org/t/tables-in-pure-markdown/81. Every half-decent markdown flavor out there has some syntax to represent tables. And they're not sooo different from each other. Table-support is essential if you are going to use markdown to document your project. Who in his right mind is arguing you should resort to HTML tables just because you use CommonMark.

[sahilTakiar]

I see thanks a bunch for the info!

[agjohnson]

@marcelstoer I was considering this use case this morning, I've raised the question on readthedocs/recommonmark#3

I share your frustration with the development speed of the CommonMark spec. I don't use Markdown, but as other authors prefer it, I'd really like to support Markdown better with Sphinx. CommonMark is definitely holding us back there some.

[marcelstoer]

I absolutely wanted to use RTD for my project, most of your stuff is great, but I also wanted to use markdown. The use of both those technologies were "non-negotiable" if you will. So I had to choose the lesser evil: CommonMark or MkDocs. The RTD-MkDocs-integration has its own fair share of shortcomings[1] (no PDF export, no HTML export, broken site search, broken fly-out menu links, broken 'Edit on GitHub' links, "under maintained" RTD theme for MkDocs) but I still opted for MkDocs.

[1] even though we're on the RTD issues list here I don't mean to say or imply the rugged integration be primarily RTDs fault.

[rodionos]

I'd like to have an option of using another markdown parser. CommonMark doesn't support tables.

[akarasulu]

It's been over a year and a half since this discussion and I'm wondering if there's any clarity on using CommonMark over MkDocs. Need to make a choice myself wondering what others are thinking and doing. Thanks!